# Quickstart

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

- A VPS or server — 8 GB RAM minimum (Ubuntu/Debian recommended)
- A Codeberg account — with a repo and at least one issue
- A second Codeberg account — for the review bot (branch protection requires a different reviewer)
- Woodpecker CI — running and connected to your repo
- An Anthropic API key — with the `claude` CLI installed and authenticated
- tmux — for persistent dev sessions

1 Clone the factory

Clone disinto onto your server. This is the factory — the code that runs your agents.

    git clone https://codeberg.org/johba/disinto.git ~/disinto
    cd ~/disinto
    cp .env.example .env

Edit `.env` with your tokens:

    # Required
    CODEBERG_TOKEN=your_codeberg_token
    REVIEW_BOT_TOKEN=your_review_bot_token

    # Woodpecker CI
    WOODPECKER_TOKEN=your_woodpecker_token
    WOODPECKER_SERVER=http://localhost:8000

    # Timeouts
    CLAUDE_TIMEOUT=7200

2 Initialize your project

`disinto init` sets up everything: clones the repo, creates the project config, adds Codeberg labels, and installs cron jobs.

    bin/disinto init https://codeberg.org/you/your-project

Expected output
`=== disinto init === Project: you/your-project Name: your-project Cloning: https://codeberg.org/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 three 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.
3. Branch protection — on Codeberg, require PR reviews and add the review bot as a write collaborator.

    # 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 Codeberg 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.