Quickstart

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

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

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

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

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.

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

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

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

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