Skip to main content

Installation

Prerequisites​

  • Python 3.11+ (use pyenv for version management)
  • Git with worktree support
  • tmux for agent session management
  • Linear account with API access

Install from Source​

# Clone the repository
git clone https://github.com/your-org/goblin.git
cd goblin

# Create virtual environment (recommended)
python3.11 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

Verify Installation​

# Check version
goblin --version

# Run tests
python -m pytest tests/ -v

# Check linting
ruff check .

Development Dependencies​

The [dev] extra includes:

  • pytest + pytest-asyncio - Testing framework
  • ruff - Linting and formatting
  • httpx - Async HTTP client

Directory Structure​

After installation, Goblin expects this workspace structure:

~/.goblin/                     # Global config directory
├── config.json               # Global settings
└── credentials/              # Linear tokens

./your-project/
├── .goblin/                  # Project-specific
│   ├── goblin.db            # SQLite database
│   ├── sessions/            # Agent tmux sessions
│   ├── screenshots/         # QA screenshots
│   └── review-checklist.md  # Custom review rules
├── worktrees/               # Git worktrees for issues
└── ...                      # Your project files

Next Steps​

After installation:

  1. Initialize your workspace
  2. Connect to Linear
  3. Add your first project