Aiflow

aiflow

aiflow turns any repository into a governed, AI-driven software-delivery pipeline with one command. It wires Claude Code together with durable task tracking, a two-layer code memory (structural graph + semantic RAG), autonomous work loops, specialist review/audit agents, token/cost controls, enforced code style, a configurable git branching model, and first-class team collaboration — so an AI agent (or a whole team of humans

• agents) can take an issue, plan it, write the code in a consistent style, test it, review it

against acceptance criteria, audit it, and ship it through a real release process.

Most people struggle to set up their AI project successfully — especially without deep AI know-how yet. This tool is built to fix exactly that: answer a few questions, get a proven, opinionated setup.

• Token-based & vendor-neutral — your own Anthropic API key or Claude Code OAuth token; git

hosts via tokens only, never OAuth. No third-party hub.

• Local-first option — run easy work on Ollama models (no key), keep top models for hard

reasoning.

• Project-scoped — secrets and settings live in the project (.env, .aiflow/config.json),

never globally.

• Cross-platform — Windows, Linux, macOS.

> 🇩🇪 Diese Anleitung gibt es auch auf [Deutsch → README.de.md](README.de.md).

Version 0.1.1 · MIT License · [Changelog](CHANGELOG.md) · 📖 Documentation site

---

Contents

1. [Why aiflow — the advantages](#1-why-aiflow--the-advantages)
2. [Feature overview](#2-feature-overview)
3. [Install](#3-install)
4. [Build a first project (walk-through)](#4-build-a-first-project-walk-through)
5. [The tools aiflow installs](#5-the-tools-aiflow-installs)
6. [Memory: why a graph and a RAG index](#6-memory-why-a-graph-and-a-rag-index)
7. [Agents — the full roster](#7-agents--the-full-roster)
8. [Slash-command skills](#8-slash-command-skills)
9. [Delivery workflow & branching models](#9-delivery-workflow--branching-models)
10. [Team collaboration (multiple members)](#10-team-collaboration-multiple-members)
11. [Configuring the remote host (GitHub / GitLab / custom)](#11-configuring-the-remote-host)
12. [Claude access, Ollama & adding more models](#12-claude-access-ollama--adding-more-models)
13. [Working with context7](#13-working-with-context7)
14. [Adding your own MCP servers](#14-adding-your-own-mcp-servers)
15. [Configuration you should tune (CLAUDE.md, team preferences, …)](#15-configuration-you-should-tune)
16. [Command reference](#16-command-reference)
17. [Token & cost optimisation](#17-token--cost-optimisation)
18. [CI/CD & building releases](#18-cicd--building-releases)
19. [Project layout](#19-project-layout)
20. [FAQ](#20-faq)
21. [Troubleshooting](#21-troubleshooting)
22. [Credits & thanks](#22-credits--thanks)
23. [Feedback, ideas & bug reports](#23-feedback-ideas--bug-reports)
24. [Contributing](#24-contributing)
25. [License](#25-license)

📖 Full documentation site: cyber93de.github.io/aiflow — including AI Basics (Claude Code, agents, memory, context windows, skills, hooks — in plain language) and a complete example-project walk-through (every question, every default, first feature end-to-end).

---

1. Why aiflow — the advantages

• A strong base config beats no config. Most AI-coding projects start with a blank Claude and

re-invent rules, memory, and workflow ad hoc — or never. aiflow's goal is one very good, universal base configuration that works everywhere out of the box and saves you roughly 70–80 % of the configuration effort compared to starting blank. The agents and rules are deliberately generic — customise them to your project (see §7 and §15), but even uncustomised they beat plain Claude.

• Production-ready code is the actual goal. aiflow's agents produce code that is meant to

ship: reusable, reliable, secure, built on current standards; they know and respect your architecture, extend it sensibly, look critically at requirements that don't fit it, and propose new layers (caching, search, service seams) where performance or other goals demand them. On demand they also report on accessibility (WCAG), modernisation potential, and security issues.

• Honest about tokens. Saving tokens is a goal — caveman, rtk, graph/RAG retrieval all attack

it — but the many quality rules (tests, reviews, gates) mean it is only partially achieved per task. The flip side pays for it: when a requirement is implemented production-ready on the first pass, you don't re-prompt, re-explain, and re-sharpen — and that is what saves tokens and time in the end.

• Better memory, fewer hallucinations. Two complementary code indexes plus durable task memory

mean the agent looks things up instead of guessing or re-reading dozens of files. See §6.

• Big token reduction. caveman (terse output ~75% fewer output tokens), rtk (CLI-output

filtering 60–90% fewer), graph + RAG retrieval (~70% fewer than reading whole files), and optional cheap/local model routing. Measured with aiflow cost.

• Team-ready. Issues live in a shared Dolt database that syncs over your git remote. Atomic

claiming prevents two people grabbing the same task; pull-before-push prevents clobbering. See §10.

• Governed & auditable. Conventional Commits, enforced Google style, a review gate against

acceptance criteria, security/quality/deps/test/perf/docs audits, a real branching + release model.

• Autonomous when you want it. The Ralph loop finishes a task unattended (locally, in a

container, or in CI) and stops at COMPLETE/BLOCKED.

• Yours, not a hub. Everything runs on your keys/tokens and your infrastructure; secrets never

leave the project.

---

2. Feature overview

| Area | What you get | |------|--------------| | Task tracking | Beads (bd) — Dolt-backed issues with dependencies, status, history; survives context resets | | Code memory | graphify (structural graph) + cocoindex-code (semantic RAG) + .claude/memory/ facts | | External docs | context7 MCP — live, version-correct library documentation | | Version control | Choose git, svn, or none at setup | | Remote host | GitHub, GitHub Enterprise, GitLab, self-managed GitLab, Bitbucket, Forgejo, Gitea, or a custom URL — token-based | | Host MCP | The matching git-host MCP is wired automatically (per remote type) | | Models | Claude (API key or OAuth) + optional Ollama local models, selectable & auto-installed | | Model routing | claude-code-router sends easy/background work to cheap/local models | | Agents | 5 delivery + 9 audit/checker + 1 brownfield specialist subagents | | Autonomy | Ralph loop (interactive / headless / containerised / CI) | | Quality | Google style, conventional commits, format/lint/test git hooks, architect+quality-gate review, static analysis on every change, objective metric targets (0 new smells/duplicates, 0 warnings), >80 % coverage + BDD E2E gates, leveled logging, .http files for REST endpoints, DB rules §3c (3NF+FKs for new schemas, brownfield schemas handled with care) | | Branching | simple / gitflow / none, PR-only, auto-release, SemVer/CalVer | | Team | shared issue DB, atomic claim, session-start auto-pull, pull-before-push, shared preferences | | Token savings | caveman + rtk on by default, graph/RAG retrieval, cost routing |

---

3. Install

Prerequisites: Node.js (LTS). Everything else aiflow can install for you.

Windows (PowerShell)

git clone https://github.com/Cyber93de/aiflow.git
cd aiflow
./install.ps1            # creates the aiflow shim + adds bin to the user PATH
aiflow doctor            # works immediately in this window; other terminals: open a new one

Linux (bash)

git clone https://github.com/Cyber93de/aiflow.git
cd aiflow
bash install.sh          # symlinks 'aiflow' onto your PATH (~/.local/bin or /usr/local/bin)
aiflow doctor

macOS (Terminal)

git clone https://github.com/Cyber93de/aiflow.git
cd aiflow
bash install.sh          # same as Linux; optional tools install via Homebrew when present
aiflow doctor

On every OS the installer asks once whether to also install git, Subversion (svn), and Ollama — so a later aiflow init only has to ask which Ollama models you want. Then:

aiflow install-deps --all   # install the rest of the toolchain (optional; init offers it too)

Or grab a packaged build from github.com/Cyber93de/aiflow/releases.

---

4. Build a first project (walk-through)

mkdir my-app && cd my-app
aiflow init                 # interactive Q&A → writes .aiflow/config.json → renders everything
aiflow init --no-token-saving   # same, but with caveman + rtk off (full, unfiltered output)

aiflow init asks (Enter = the sensible default; token-saving + intensive graph memory are on):

1. caveman / rtk — token-saving output + CLI filtering (default on).
2. graphify (structural graph) and cocoindex-code (semantic RAG) — code memory (default on).
3. task-master, filesystem MCP, context7 MCP (default on).
4. Memory — enable persistent memory, graph learning, and intensity (default aggressive).
5. Claude access — apikey (ANTHROPICAPIKEY) or oauth (claude setup-token).
6. Version control — git / svn / none.
7. Remote host — `github | github-enterprise | gitlab | gitlab-self | bitbucket | forgejo |

gitea | custom | none`, plus which host MCP to wire. Token-based.

1. Sync rule — ask to push + Dolt-sync each time a Beads issue is closed; auto-pull at session start.
2. Ollama — set it up? which models? (qwen3-coder recommended).
3. Shared team preferences — code style, etc.
4. Project aim / architecture / OS / IDE, and the git branching model (if VCS = git).

> Don't skip the project aim — it's the cheapest quality lever. The aim tunes Claude to your > project: every agent reads it before planning or coding. Tell it to aiflow during init (question > 11) or later via aiflow change-settings — or write it manually into > .claude/memory/project-aim.md and CLAUDE.md §1. A good aim is 2–4 plain sentences: > what the product does, for whom, the target architecture, and the quality bar. Example: > "Order-management REST API for our internal shops. Hexagonal architecture on PostgreSQL. > Correctness and auditability beat raw speed; every endpoint ships fully tested."

Then fill secrets and start:

# edit .env → your git-host token + (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN)
aiflow shell                # loads .env, launches Claude Code with all MCPs wired

Inside the session:

/beads:ready                # what's ready to work
bd create "Add health endpoint" -t task --claim   # create + claim a task
/implement                  # implementer builds it (code + tests, Google style)
/review-ac                  # reviewer gates it against acceptance criteria

Existing codebase (brownfield)? aiflow init detects it and offers aiflow onboard, which learns the code into .claude/memory/, CLAUDE.md, and arc42 docs so the agent starts informed — and proposes a project aim from the understanding it built. The proposal is not silently adopted: the onboarder asks you to confirm or correct it (headless runs mark it PROPOSED — please confirm in project-aim.md). Follow up with aiflow modernize-check for a modernisation report the architect can turn into beads:

Build the code indexes any time with aiflow index (graph + RAG).

---

5. The tools aiflow installs

aiflow install-deps installs only what your config enables (--all = full set). All are user-space; Docker is never auto-installed.

Core (always): Claude Code · Beads (bd) · Dolt (Beads' database backend) · jq · the git-host CLI matching your remote (gh/glab).

Optional (when enabled): claude-task-master · claude-code-router · rtk · graphify (needs uv) · cocoindex-code (ccc, needs uv) · Ollama (+ your selected models).

Headless container runs (docker/run.sh) and the GitHub MCP work with Podman or Docker — install either one yourself (never auto-installed).

aiflow doctor shows what's present, plus a per-project summary (remote + host MCP, VCS, Ollama models, memory: graph/rag/context7 + intensity).

---

6. Memory: why a graph and a RAG index

LLMs forget between sessions and burn tokens re-reading files. aiflow gives the agent a layered context stack so it routes a question to the cheapest source that answers it. The full routing table is written to .claude/memory/memory-policy.md:

| Need | Source | Why | |------|--------|-----| | Current task, deps, decisions, session state | Beads (bd) | structured work memory, survives compaction | | Durable project facts / gotchas / env quirks | memory files (.claude/memory/) | prose not in code/git | | Where a symbol is defined, who calls it, dependency direction | graphify (MCP) | exact structural graph — no re-scan | | "Find the code about concept X" / semantic / fuzzy | cocoindex-code (ccc / MCP) | AST-aware RAG, local embeddings, ~70% fewer tokens | | External library/framework API docs | context7 (MCP) | live upstream docs, avoids hallucination | | Anything still unresolved | read the file(s) | only after graph + RAG narrowed the target |

Why a graph? Code is a graph (imports, calls, types). A graph answers structural questions ("who calls parseToken? what does auth depend on?") exactly and cheaply — no guessing, no re-reading, and it discourages DRY violations because the agent can see existing code.

Why also RAG? A graph doesn't answer fuzzy questions ("where is retry logic handled?"). cocoindex-code chunks the code AST-aware, embeds it locally (sentence-transformers, no API key), and searches by meaning — ~70% fewer tokens than opening files. It's incremental: only changed files re-embed.

Refresh both indexes with one command after significant changes:

aiflow index            # = graphify build  +  ccc index   (incremental)

---

7. Agents — the full roster

Specialist subagents live in .claude/agents/. Claude picks one by its description, or you invoke it explicitly. The shipped agents are deliberately generic — a strong, universal starting point, not the finish line: customise them to your project's needs by editing their markdown (prompt, allowed tools:, model:) — e.g. your domain language, your review focus, your test stack.

Delivery agents (do the work)

| Agent | Role | |-------|------| | architect | System design — produces ADRs, arc42 updates, and a task breakdown. No feature code. | | planner | Turns a goal/epic/issue into small Beads tasks with testable acceptance criteria + real dependencies. | | implementer | Senior engineer for exactly one ready bead — pre-analysis (architecture fit, effort, complexity) before code, targeted refactoring when needed, SOLID/DRY/KISS/YAGNI, testable by design (DI, deterministic), proven frameworks/patterns over self-built, PO-level questions with recorded decisions, quality gates (static analysis, >80 % coverage, BDD E2E, logging, .http files, metric targets). | | reviewer | Architect and quality gate in one — architecture/design/risk review (layers, module boundaries, SOLID, tech debt, over-/under-engineering, vulnerabilities, concurrency, breaking changes) plus the objective

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cyber93de
• Source: cyber93de/aiflow
• License: MIT
• Homepage: https://cyber93de.github.io/aiflow/

Install and usage instructions live in the source repository linked above.