Skip to main content

Quick Start

Get Goblin running in under 5 minutes.

Initialize Workspace​

# Create the .goblin directory and database
goblin init

This creates:

  • .goblin/goblin.db - SQLite database
  • .goblin/sessions/ - Agent session storage
  • .goblin/review-checklist.md - Default review guidelines

Authenticate with Linear​

Get your Linear API token from Linear Settings → API.

goblin auth --token lin_api_YOUR_TOKEN_HERE --org your-org-name

This stores credentials securely and validates the connection.

Add a Project​

Link a git repository to a Linear team:

# Add current directory, linking to the ENG team
goblin project add . --team ENG

# Or specify a path
goblin project add ./my-app --team MOBILE

Configure Pipeline (Optional)​

Set up automation options:

# Set bot user for auto-assignment
goblin pipeline config -p my-app --assignee-id YOUR_BOT_USER_ID

# Enable Docker Compose for preview environments
goblin pipeline config -p my-app --docker-compose docker-compose.yml

# Enable Playwright for visual testing
goblin pipeline config -p my-app --playwright

# Set test URLs
goblin pipeline config -p my-app --test-urls "http://localhost:3000"

# View current config
goblin pipeline config -p my-app --show

Start the Daemon​

The daemon runs 24/7, monitoring Linear for assigned issues:

# Start in foreground (for development)
goblin daemon

# Or run in background with systemd (production)
# See: Cloud Deployment guide

Start a Pipeline Manually​

For testing, you can start a pipeline for a specific issue:

# Start pipeline for ENG-123
goblin pipeline start ENG-123

# Check status
goblin status

Monitor Progress​

# View dashboard (opens web UI)
goblin dashboard

# Check status in terminal
goblin status

# Attach to an agent session
goblin attach AGENT_ID

What Happens Next​

When an issue is assigned to your bot user in Linear:

  1. SCOPE - Scoper agent analyzes the issue and creates a plan
  2. BUILD - Builder agent implements the code in an isolated worktree
  3. REVIEW - Reviewer agent checks the diff for issues
  4. TEST - Tester agent runs tests and validates QA steps
  5. DONE - PR is created, issue reassigned for human review

Troubleshooting​

Daemon not starting​

# Check Python version
python --version  # Should be 3.11+

# Verify Linear connection
goblin sync -p my-app

Issues not being detected​

# Verify bot user ID is configured
goblin pipeline config -p my-app --show

# Check daemon logs
goblin daemon  # Watch output

Next Steps​