# Quickstart

from zero to your first automated PR
← disinto.ai
Prerequisites

- A VPS or server — 8 GB RAM minimum (Ubuntu/Debian recommended)
- Docker + Docker Compose — the stack runs as containers (Forgejo + Woodpecker CI included)
- An Anthropic API key — with the `claude` CLI installed and authenticated
- tmux — for persistent dev sessions

1 Clone disinto

Clone the factory onto your server and configure your API key.

    git clone https://codeberg.org/johba/disinto.git ~/disinto
    cd ~/disinto
    cp .env.example .env
    # Edit .env with your Anthropic API key

2 Initialize your project

`disinto init` starts the full stack (Forgejo + Woodpecker CI), creates your repo, clones it locally, generates the project config, adds labels, and installs cron jobs — all in one command.

    bin/disinto init user/your-project

Use `disinto up` / `disinto down` later to restart or stop the stack.

Expected output
`=== disinto init === Project: you/your-project Name: your-project Cloning: http://localhost:3000/you/your-project.git -> /home/you/your-project Branch: main Created: /home/you/disinto/projects/your-project.toml Creating labels on you/your-project... + backlog + in-progress + blocked + tech-debt + underspecified + vision + action Created: /home/you/your-project/VISION.md Cron entries installed Done. Project your-project is ready.`

Optional flags:

- `--branch main` — set the primary branch (auto-detected by default)
- `--ci-id 3` — Woodpecker CI repo ID (0 = no CI)
- `--repo-root /path/to/clone` — custom clone location
- `--yes` — skip confirmation prompts

3 Prepare your repo

Your project needs two things before agents can work on it:

1. A CI pipeline — at least one `.woodpecker/*.yml` file. Agents wait for CI before reviewing or merging.
2. A CLAUDE.md — project context that agents read before every task. Describe your tech stack, how to build/test, coding conventions, and directory layout.

Branch protection and the review bot are pre-configured on the built-in Forgejo. If you're connecting to an external forge, set those up manually.

    # Create CLAUDE.md in your project
    cat > ~/your-project/CLAUDE.md <<'EOF'
    # Your Project

    ## Tech stack
    - Node.js, React, PostgreSQL

    ## How to build and test
    npm install && npm test

    ## Conventions
    - Use TypeScript, ESLint, Prettier
    - Tests in __tests__/ directories
    EOF

    cd ~/your-project
    git add CLAUDE.md && git commit -m "Add CLAUDE.md for agent context"
    git push

4 File your first issue

Create an issue on the forge with the `backlog` label. Be specific — the dev-agent works best with clear acceptance criteria.

    # Title: Add health check endpoint
    # Label: backlog
    # Body:

    ## Problem
    The app has no health check endpoint for monitoring.

    ## Approach
    Add a GET /health route that returns { "status": "ok" }.

    ## Acceptance criteria
    - [ ] GET /health returns 200 with JSON body
    - [ ] Response includes uptime in seconds
    - [ ] Test covers the new endpoint

That's it. The factory takes over from here.

5 Watch the lifecycle

Within minutes, the agents start working. Here's what happens:

issue filed → dev-agent picks it up → PR opened → CI runs → review-agent reviews → merged

Monitor progress with:

    # Check factory status
    bin/disinto status

    # Watch the dev-agent log
    tail -f /tmp/dev-agent.log

    # Watch the review log
    tail -f /tmp/review.log

Expected timeline
`~2 min dev-poll finds the issue, claims it ~5 min dev-agent opens a PR with the implementation ~2 min CI runs (Woodpecker) ~2 min review-agent approves or requests changes ~1 min PR merges, issue closes automatically`

If the review-agent requests changes, the dev-agent addresses them automatically. The loop repeats until the PR is approved and merged.

6 Verify everything works

    # Factory status — shows active sessions, backlog depth, open PRs
    bin/disinto status

    # Check your repo — the PR should be merged
    cd ~/your-project
    git pull
    git log --oneline -5

You should see a merge commit with the dev-agent's implementation. The issue is closed, the branch is deleted.

## What's next

Now that the factory is running:

- Write VISION.md — describe where the project is headed. The planner reads it weekly and creates issues to close gaps.
- File more issues — the dev-agent processes them one at a time, in order. Use `## Dependencies` sections to control sequencing.
- Watch the dashboard — disinto.ai/dashboard shows live factory metrics.
- Read the architecture — understand how the agents work together.