Disinto runs a continuous loop: vision defines direction, agents derive work and execute it, results feed back into the next cycle.
++ planner reads VISION.md + | + v + creates backlog issues + | + v + dev-agent picks issue --> implements in worktree --> opens PR + | + v + Woodpecker CI runs tests + | + v + review-agent reviews PR --> approves or requests changes + | | + v (approved) v (changes requested) + PR merges dev-agent addresses feedback + | | + v +--> CI re-runs --> review again + planner sees progress, plans next cycle ++
Each project processes one issue at a time. No concurrent PRs, no merge conflicts, no context switching. The pipeline is deliberately sequential.
+Each agent has a single responsibility. They communicate through git, the Codeberg API, and the filesystem.
+When the dev-agent runs in a persistent tmux session, it signals progress by writing to a phase file. The orchestrator watches this file and injects events (CI results, review feedback) back into the session.
+| Phase | +Meaning | +Next event | +
|---|---|---|
| awaiting_ci | +PR pushed, waiting for CI | +Orchestrator injects CI result | +
| awaiting_review | +CI passed, waiting for review | +Review-agent injects feedback | +
| needs_human | +Blocked on a human decision | +Matrix notification sent | +
| done | +PR merged, work complete | +Session cleaned up | +
| failed | +Unrecoverable error | +Escalated to supervisor | +
Phase files live at /tmp/dev-session-{project}-{issue}.phase. The protocol is intentionally simple — a plain text file, one line, no daemons.
The vault sits between agents and dangerous actions. Before an agent can execute a risky operation (force push, deploy, delete), the vault reviews the request.
+Auto-approve — safe, well-understood operations pass through instantly. Escalate — risky or novel operations get sent to a human via Matrix. Reject — clearly unsafe actions are blocked.
+You define the boundaries. The vault enforces them. This is what lets you sleep while the factory runs.
+The planner runs weekly. It compares the current state of the codebase against VISION.md and creates issues for anything missing. It also triages predictions filed by the predictor.
+The predictor runs daily. It analyzes CI logs, git history, and resource metrics to detect patterns — recurring test failures, disk usage trends, code churn hotspots. Predictions are filed as issues for the planner to triage.
+Together, they create a feedback cycle: the predictor observes, the planner directs, and the dev-agent executes.
+Disinto is deliberately minimal. No Kubernetes, no message queues, no microservices.
+Bash scripts — every agent is a shell script. No compiled binaries, no runtimes to install.
+Claude CLI — AI is invoked via claude -p (one-shot) or claude (persistent tmux sessions).
Cron — agents are triggered by cron jobs, not a daemon. Pull-based, not push-based.
+Codeberg + Woodpecker — git hosting and CI. All state lives in git and the issue tracker. No external databases.
+Single VPS — runs on an 8 GB server. Flat cost, no scaling surprises.
+.env or TOML project files.+disinto/ +├── dev/ dev-poll.sh, dev-agent.sh, phase-handler.sh +├── review/ review-poll.sh, review-pr.sh +├── gardener/ gardener-run.sh (cron executor) +├── predictor/ predictor-run.sh (daily cron executor) +├── planner/ planner-run.sh (weekly cron executor) +├── supervisor/ supervisor-run.sh (health monitoring) +├── vault/ vault-poll.sh, vault-agent.sh, vault-fire.sh +├── action/ action-poll.sh, action-agent.sh +├── lib/ env.sh, agent-session.sh, ci-helpers.sh +├── projects/ *.toml per-project config +├── formulas/ TOML specs for multi-step agent tasks +├── bin/ disinto CLI entry point +└── docs/ internal protocol docs ++
claude CLI installed and authenticatedClone 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 .envEdit .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=7200disinto 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=== 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 promptsYour project needs three things before agents can work on it:
+.woodpecker/*.yml file. Agents wait for CI before reviewing or merging.# 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 pushCreate 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 endpointThat'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~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.
+# 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 -5You should see a merge commit with the dev-agent's implementation. The issue is closed, the branch is deleted.
+Now that the factory is running:
+## Dependencies sections to control sequencing.The code is public. The factory is running. See for yourself.