aiflow

aiflow turns any repository into a governed, AI-driven software-delivery pipeline with one command. It wires Claude Code, GitHub Copilot, and OpenAI Codex CLI — agent-agnostic, pick any combination — 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 with automated release workflows, and first-class team collaboration — so an AI coding 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.

• Agent-agnostic — Claude Code (full feature set: subagents, hooks, slash-commands), GitHub Copilot, and OpenAI Codex CLI all read the same shared AGENTS.md + get their own rendered MCP config. The Ralph loop works across all three via open-ralph-wiggum. See Multi-Agent Support.
• 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.

Version 0.9.0 · MIT License · Changelog · 📖 Documentation site

---

Contents

1. Why aiflow — the advantages
2. Feature overview
3. Install
4. Build a first project (walk-through)
5. The tools aiflow installs
6. Memory: why a graph and a RAG index
7. Agents — the full roster
8. Slash-commands and Skills
9. Delivery workflow & branching models
10. Team collaboration (multiple members)
11. Configuring the remote host (GitHub / GitLab / custom)
12. Claude access, Ollama & adding more models
13. Working with context7

📖 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.
• Token control across agents. Shared compact instructions, task-loaded skills and targeted file reads work across agents. Claude can additionally use caveman, RTK and role-based model routing; Graphify, CocoIndex and CodexSaver are opt-in. Measure actual usage 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; per-activity model tiers put architecture/planning/review/security on Opus (or Fable), implementation + tests on Sonnet, mechanical scans on Haiku
Architecture rules	Binding, every language: layered with inward dependencies, interfaces at every seam, DAO + DTO separation, domain objects never on the wire, reuse/generics over duplication. A task that doesn't fit is asked about before it's built
Agents	1 orchestrator + 5 delivery + 9 audit/checker + 1 brownfield specialist subagents, wired into one documented network
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

---

3. Install

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

Windows: do this before you clone. aiflow itself runs in PowerShell + Git Bash, but anything that compiles native code (C/C++, node-gyp, Python C-extensions) belongs in WSL — never MinGW/MSYS2. Skipping this is the #1 cause of a failed Windows setup.

1. Enable Intel VT-x / AMD SVM Mode in the BIOS/UEFI (Task Manager → Performance → CPU → Virtualization: Enabled).
2. Admin PowerShell: wsl --install → reboot (enables WSL + Virtual Machine Platform).
3. wsl --install -d Ubuntu, start it once; wsl -l -v must show VERSION 2.
4. Inside WSL: sudo apt update && sudo apt install -y build-essential → gcc/g++; add cmake, python3-dev, a cross-toolchain, … as your project needs.

Full walkthrough incl. why not MinGW: docs — Windows prerequisites. aiflow doctor checks all four steps.

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; optional retrieval MCPs stay off for small projects):

1. caveman / rtk — optional output shaping and CLI filtering (enabled by default for Claude sessions).
2. graphify and cocoindex-code — opt-in structural and semantic retrieval for larger repositories.
3. task-master, filesystem MCP, GitKraken — opt-in; Context7 is enabled by default.
4. Memory — enable persistent memory, graph learning, and intensity (default aggressive).
5. Claude access — apikey (ANTHROPIC_API_KEY) 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.
8. Sync rule — ask to push + Dolt-sync each time a Beads issue is closed; auto-pull at session start.
9. Ollama — set it up? which models? (qwen3-coder recommended).
10. Shared team preferences — code style, etc.
11. 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 AGENTS.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/, AGENTS.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:

---

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): Beads (bd) · Dolt (Beads' database backend) · jq · the git-host CLI matching your remote (gh/glab).

Coding agent CLIs (per agents.*): Claude Code (agents.claude, default on) · GitHub Copilot CLI (agents.copilot, npm i -g @github/copilot) · OpenAI Codex CLI (agents.codex, npm i -g @openai/codex). Pick any combination — see Multi-Agent Support.

Optional (when enabled): claude-task-master · claude-code-router · rtk · graphify (needs uv) · cocoindex-code (ccc, needs uv) · Ollama (+ your selected models) · CodexSaver (codexsaver.enabled, needs agents.codex + Python — cost-aware MCP router for Codex CLI, clone + editable pip install, no published package).

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.

Not on Claude Code? Subagents/hooks/slash-commands below are Claude Code-only — GitHub Copilot and OpenAI Codex CLI follow the same roles and rules manually from the shared AGENTS.md (§5 there). See Multi-Agent Support.

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 §3a checklist; suggestions persisted as beads for the next loop. Verdict PASS / CHANGES REQUIRED.
tester	Test/QA engineer — negative/edge/boundary/exception/invalid-input tests plus test-quality audit (assertions, determinism, independence); runs when the pre-analysis flags high risk/complexity; reports bugs instead of weakening tests.

Audit agents (manual, read-only on code, file prioritised Beads)

Agent	Command	Files issues labelled
security-advisor	aiflow security-check	[security-advisor]
quality-check	aiflow quality-check	[technical issue]
dependency-auditor	aiflow dependency-check	[dependency]
test-gap-advisor	aiflow test-gap	[test gap]
performance-advisor	aiflow perf-check	[performance]
docs-sync	aiflow docs-check	[docs]
accessibility-checker	aiflow a11y-check	[accessibility] — strict WCAG 2.2 AA audit of all UI surfaces; also recommends an automated a11y tool for the E2E suite (axe-core/Pa11y/Lighthouse CI). Not part of the delivery loop.
requirements-check	aiflow requirements-check	report only (advisory; grades issue quality vs architecture; no changes)
modernization-advisor	aiflow modernize-check	report only — walks the whole brownfield codebase and proposes modernisation concepts (microservices over monoliths, REST/cloud-native over SOAP/legacy MQ, git over svn, supported stacks, missing unit/BDD/E2E test frameworks) to .aiflow/modernization-report.md; the architect reviews and optionally feeds them into Beads. Not part of the delivery loop.

Brownfield agent

Agent	Role
onboarder	Studies an existing codebase and persists what it learns into .claude/memory/, AGENTS.md, and arc42 — future sessions start informed; proposes a project aim and asks you to confirm it. Writes docs/memory only.

What every delivery agent has in common: production-ready output only (careful with low-maturity tech — reviewer and tester flag it), small classes / KISS (divide & conquer + interfaces instead of giant classes), state-of-the-art by default (legacy choices like SOAP or XML-over-REST are questioned, never silently built), monolith avoidance, and deliberate data/performance choices (Redis/SQLite/Elasticsearch considered where they pay off). Full per-agent detail: docs → Agents.

---

8. Slash-commands and Skills

Two different Claude Code mechanisms, both shipped:

Slash-commands — explicitly triggered, .claude/commands/:

• Delivery: /orchestrate <goal|bead> (entry point — the orchestrator routes every step below), /intake-issue <n> (pull a GitHub/GitLab/Bitbucket issue → Beads), /decompose <goal|prd> (task-master → Beads), /plan-epic, /implement [bead] [ralph|no-ralph] (pre-analysis first; unspecified → the implementer decides automatically — or honours a "use the Ralph loop" note written into the issue itself), /review-ac, /arch "<question>".
• Audits: /security-check, /quality-check, /requirements-check, /dependency-check, /test-gap, /perf-check, /docs-check, /a11y-check (strict WCAG), /modernize-check (brownfield modernisation report), /ponytail-review (over-engineering audit of the current diff).
• Brownfield / orientation: /onboard, /explain <path>, /standup.

Beads and the Ralph loop also ship plugin commands (/beads:ready, /beads:decision, /ralph-loop).

Skills — shared checklists live in .agents/skills/<name>/SKILL.md and are mirrored to .claude/skills/<name>/SKILL.md; skill discovery varies by agent and Claude Code can suggest a match. An agent is a role (who acts, with what authority, in what order); a skill is knowledge several roles need — the implementer writing an endpoint and the reviewer checking it read the same list. Full catalogue: Skills.

• Technology stacks — stack-embedded (C/C++ firmware: HAL separation, no allocation after init, ISR discipline, host tests against a mocked HAL), stack-mobile (Flutter/Dart, Kotlin/ Android, Swift/iOS: layering, state management, process death, offline/sync, Keystore/Keychain), stack-web-frontend (Angular/React/Vue: feature slices, server vs client state, XSS and token handling, Core Web Vitals, i18n, a11y), stack-backend (Spring/Quarkus/Jakarta, .NET, Rust, Node, Go, Python: hexagonal layering with ports, transaction boundaries, resilience, observability, FOSS-first).
• Integration & data — api-design (REST versioning/idempotency/problem+json/OpenAPI/ .http, when SOAP is legitimate and how to migrate off it, GraphQL/gRPC trade-offs), messaging-events (Kafka/RabbitMQ/NATS, idempotent consumers, transactional outbox, ordering, DLQs, sagas), data-storage (SQL default, when NoSQL is justified, embedded DBs, Redis with real cache invalidation, Elasticsearch as a derived read layer), cloud-native (container images, K8s probes/limits/rollout/secrets, EC2, modular monolith vs microservices).
• security — OWASP Top 10 as a review raster + ASVS levels, IAM least privilege (roles, short-lived credentials, rotation), API authN/authZ, secrets, crypto, supply chain. The security-advisor uses the same raster.
• seo-optimization — SEO for any web-facing project (HTML, GitHub Pages, static sites, docs sites, landing pages, blogs, Next.js, Astro, Hugo, Jekyll, VuePress, VitePress, React, Vue, Svelte, Angular, …): meta tags, Open Graph/Twitter Cards, JSON-LD structured data, robots.txt/ sitemap.xml, canonical URLs, heading hierarchy, alt text, Core Web Vitals, GitHub Pages specifics (base URL, 404, social preview, RSS). Auto-offers when web content is present/being created; ends with an SEO report (fixed / still open / priority / recommendations).
• ponytail — YAGNI decision ladder before writing new code: does it need to exist? already in the codebase? stdlib? native platform feature? installed dependency? a one-liner? only then the minimum-viable new code. Off by default — enable with ponytail.enabled/.mode (full/lite/ultra) via aiflow init or aiflow change-settings. /ponytail-review audits a diff for over-engineering regardless of the toggle.
• memory-setup — the full memory/context-routing picture: what to save, the priority order (Beads → memory files → graphify → cocoindex-code → context7), shared team preferences, Ollama routing. AGENTS.md §8 keeps the short toggle + essentials; this skill has the rest.

Add your own by dropping a new <name>/SKILL.md into .claude/skills/ — see the shipped ones for the expected frontmatter (name, description) and structure. Quote a description that contains a colon — description: two hats: architect … is invalid YAML, and nothing warns you: a skill or command silently falls back to its body text (so it stops matching the trigger words you wrote), and an agent is dropped from the roster entirely. The generated project's pre-commit hook runs .github/scripts/check-frontmatter.py over every agent, command, and skill as soon as you stage one, and CI runs it again on every push. The hook needs python3/python + PyYAML; without them it says so and skips, so CI stays the backstop.

---

9. Delivery workflow & branching models

Issue (GitHub / GitLab / Bitbucket / …)
  └─ /intake-issue ─▶ Beads tasks (with acceptance criteria)
       └─ /decompose (task-master) ─▶ subtasks + dependencies
            └─ bd ready --claim ─▶ pick & claim a task
                 └─ /implement ─▶ code + tests, Google style      (implementer)
                      └─ /review-ac ─▶ gate vs acceptance criteria (reviewer)
                           └─ commit (Conventional Commits + bead id) ─▶ PR ─▶ release
                                └─ aiflow close-sync ─▶ push + Dolt-sync issues

One feature end to end — task, pre-analysis, PO question with recorded decision, versioned + secured API, tests + .http file, review gate, close:

Branching models (aiflow init / change-settings, only when VCS = git). aiflow writes .aiflow/branching.json + a readable docs/branching.md, creates permanent branches, seeds VERSION, and installs enforcement:

• Model — simple (main + develop) · gitflow (feature/*/bugfix/* from develop, hotfix/* from main) · none.
• main is restricted (gitflow) — only develop, hotfix/*, or chore/* may ever land on main; feature/*/bugfix/* always merge to develop. Doc-only and CI/workflow-file-only changes count as chore/*.
• Strict rules — enforce branch sources/targets and naming.
• PR-only — no direct push to main/develop; merge only via a validated PR.
• Auto-release — develop carries X.Y.0-SNAPSHOT; merging into main strips it (minor release). aiflow hotfix <name> bumps a hotfix branch to X.Y.(Z+1)-HOTFIX; merging into main strips it (patch release) and also merges the hotfix into develop. chore/* → main never releases, and main itself is never allowed to carry a -SNAPSHOT/-HOTFIX version. Releasing always needs explicit, human-approved confirmation — never automatic.
• Version strategy — SemVer or CalVer; optional release tags.
• chore/* — chore branches independent of feature/hotfix rules.

Enforcement: the pre-push hook blocks direct pushes to protected branches, blocks feature/*/bugfix/* merges onto main, and rejects any push to main with a -SNAPSHOT/-HOTFIX version; aiflow protect applies real server-side branch protection on GitHub; aiflow release [--yes] [--push] prints a dry run, and only bumps the version, tags, and bumps develop once run with --yes.

---

10. Team collaboration (multiple members)

Beads issues live in a shared Dolt database that syncs via refs/dolt/data on your git remote — one issue graph for the whole team, no extra server.

• Sync at session start. A SessionStart hook auto-runs bd dolt pull (safe, best-effort, never pushes; opt-out via sync.pullOnStart). Or manually: aiflow sync.
• Claim atomically. bd ready --claim / bd update <id> --claim sets assignee = you + status = in_progress in one step, so two people never grab the same task. bd ready --unassigned shows free work.
• Pull before push, always. aiflow sync and aiflow close-sync pull first, so you merge teammates' issue changes instead of clobbering them. On conflict: bd dolt pull (merge), resolve, push. Never force-push.
• Status is the coordination signal. Keep it current; stale status = duplicate work.
• Queue mode: a closed task is not a finished session. After every close the agent refreshes the queue and starts the next task — aiflow next ranks it (priority → unblocks-most → continuation of the bead just closed). It stops only for a real reason: nothing actionable, everything blocked, you said stop, or a decision only you can make. A Stop hook hands the next task back once if the agent forgets; disable with .aiflow/config.json → beads.queueMode = false or AIFLOW_QUEUE_MODE=off.
• Discovered work → a new bead (--deps discovered-from:<id>); decisions → /beads:decision (recorded with rationale) so the whole team sees the why.
• Shared preferences (code style, language) live in a committed .aiflow/team-prefs.json — the whole team inherits them; personal tweaks stay local.

---

11. Configuring the remote host

aiflow is token-based only — no OAuth for git hosts. Pick the type at init/change-settings; the matching CLI and MCP are wired automatically.

Remote type	Base URL	Token env (.env)	Host MCP wired
github	github.com	GITHUB_TOKEN	github-mcp-server
github-enterprise	your GHE URL	GITHUB_TOKEN	github-mcp-server (GITHUB_HOST set)
gitlab / gitlab-self	gitlab.com / your URL	GITLAB_TOKEN	server-gitlab (GITLAB_API_URL set)
bitbucket	your URL	BITBUCKET_TOKEN	atlassian-bitbucket
forgejo / gitea	your URL	GIT_REMOTE_TOKEN	gitea-mcp-server (GITEA_URL set)
custom	any URL	your env var	pick from the list (or none)
none	—	—	none — fully local, no MCP for a git host

GitHub example: create a PAT with repo + issues + pull_requests scope → put it in .env as GITHUB_TOKEN. GitLab example: create a personal access token with api scope → GITLAB_TOKEN. For self-managed/enterprise, give the base URL at init; aiflow wires the API URL / host into the MCP.

Each host also gets a predefined release-publish workflow, written once (never overwritten if you already have one): .github/workflows/release.yml, .gitlab-ci.yml, .gitea/workflows/release.yml, .forgejo/workflows/release.yml, or bitbucket-pipelines.yml. It triggers on a version tag push (the one aiflow release --push creates) and publishes a release entry/note on the host — it never bumps versions itself, that stays the local, human-confirmed aiflow release --yes step.

GitKraken is a git client, not a host — a separate gitkraken.enabled toggle wires its MCP (via the gk CLI) alongside whichever remote type you picked above, or on its own with remote.type: none.

Beads issue sync (bd github/bd gitlab) and Dolt sync use the same remote. Change any of this later with aiflow change-settings (re-renders .mcp.json, hooks, everything).

---

12. Claude access, Ollama & adding more models

Claude access (.aiflow/config.json → claude.auth, both supported, OAuth wins if both set):

• apikey → ANTHROPIC_API_KEY (pay-per-use, console.anthropic.com).
• oauth → run claude setup-token → CLAUDE_CODE_OAUTH_TOKEN (uses your Claude plan).

Ollama (local, no API key). Enable at init, or:

aiflow ollama add qwen3-coder     # add a model to config + pull it
aiflow ollama pull                # pull every model listed in config
aiflow ollama list                # what's installed

Selected models are written into .aiflow/router-config.json as a provider, so they're actually used for easy/background work:

aiflow shell --router             # routes cheap/background steps to local models

Adding more / cloud models (DeepSeek, OpenRouter, Gemini, …): add the provider + key to ~/.claude-code-router/config.json (never committed) and enable router in the config. .env also lists optional keys (DEEPSEEK_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY). Route trivial steps to cheap models, keep top Claude models for hard reasoning; measure with aiflow cost.

---

13. Working with context7

context7 is an MCP server that fetches live, version-correct documentation for the libraries you use — so the agent codes against the real current API instead of a stale memory. It's enabled by default (mcp.context7).

• In a session, just ask normally ("use the latest zod schema API") — the agent calls context7 to pull current docs. You can also nudge it: "check context7 for the current Prisma migrate API".
• It works keyless; a CONTEXT7_API_KEY in .env raises rate limits.
• Pair it with the code indexes: context7 = external library docs, graphify/cocoindex = your code.

---

14. Adding your own MCP servers

aiflow generates .mcp.json from .aiflow/config.json, but you can add any extra MCP server — your edits to servers aiflow doesn't manage are preserved on re-render. Add an entry:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-mcp-server"],
      "env": { "MY_TOKEN": "${MY_TOKEN}" }   // secrets via .env, never inline
    }
  }
}

Then allow it in .claude/settings.json under permissions.allow (e.g. "mcp__my-server") and put any secret in .env (gitignored). For community-vetted servers, browse the marketplace: npx claude-code-templates@latest. Tip: prefer a focused MCP over a broad one — fewer tools = less context and fewer wrong turns.

---

15. Configuration you should tune

Everything is driven by .aiflow/config.json (committed, no secrets). Edit it interactively with aiflow change-settings (re-renders .mcp.json, hooks, branching, memory) — switch version control (git/svn), pick different Ollama models, or turn token saving off entirely with --no-token-saving:

The files most worth tuning:

• AGENTS.md — the operating rules every agent reads (project overview, architecture hints, code style, task workflow, git rules, the memory/context stack, communication). Fill the [EDIT ME] blocks (§1 overview, §2 architecture) — this is the single biggest quality lever.
• .aiflow/team-prefs.json ("preferences") — shared, versioned team/user preferences: code style preset, language, conventions. Committed so the team inherits them; overrides AGENTS.md §3.
• .claude/memory/ — project-aim.md (goal + architecture), dev-environment.md, memory-policy.md (the retrieval routing + learning intensity). Keep these current.
• .claude/settings.json — permissions (allow/deny), hooks (caveman, formatter, beads-sync), MCP allow-list.
• .aiflow/branching.json / docs/branching.md — the branching + release model.
• .env — all tokens/keys (gitignored, never global).

Shape of config.json:

{
  "caveman":  { "enabled": true, "mode": "full" },
  "rtk":      { "enabled": true },
  "router":   { "enabled": false },
  "graphify": { "enabled": true },
  "taskmaster": { "enabled": true },
  "mcp":      { "filesystem": true, "context7": true, "cocoindex": true },
  "memory":   { "enabled": true, "graph": true, "intensity": "aggressive" },
  "claude":   { "auth": "apikey" },
  "vcs":      { "system": "git" },
  "remote":   { "type": "github", "baseUrl": "https://github.com",
                "api": "github-api", "tokenEnv": "GITHUB_TOKEN", "mcp": "github" },
  "sync":     { "askOnClose": true, "pullOnStart": true },
  "ollama":   { "enabled": false, "url": "http://localhost:11434", "models": [] },
  "teamPrefs":{ "enabled": false, "codeStyle": "google" },
  "project":  { "aim": "…", "architecture": "…" },
  "dev":      { "os": "windows", "ide": "vscode" },
  "git":      { "model": "gitflow", "strict": true, "prOnly": true,
                "autoRelease": true, "versionStrategy": "semver", "releaseTags": true, "chore": true }
}

---

16. Command reference

aiflow init [path] [--force] [--no-git] [--no-beads] [--yes] [--no-token-saving]
                                   bootstrap a project (--no-token-saving = caveman + rtk off)
aiflow install-deps [--all]        install missing tools (enabled in config; --all = full set)
aiflow change-settings [--no-token-saving]   re-adjust config, then re-render everything
aiflow shell [--router]            load .env then launch Claude Code (--router = cheap/local models)
aiflow sync [pull|push|both]       team sync: git + Beads(dolt) pull/push
aiflow close-sync <id>             on issue close: prompt to push + Dolt-sync the remote
aiflow next [--after <id>] [--claim] [--json]  next ready Beads task, ranked (queue mode)
aiflow ollama [pull|add <m>|list]  manage local Ollama models
aiflow index                       refresh code memory: graphify (graph) + cocoindex (RAG)
aiflow ralph "<prompt|bead id>"    run the headless Ralph loop
aiflow onboard                     learn an existing codebase into memory + AGENTS.md + arc42
aiflow security-check | quality-check | requirements-check | dependency-check
aiflow test-gap | perf-check | docs-check | a11y-check   on-demand audits → Beads issues
aiflow modernize-check             brownfield modernisation concepts → report for the architect
aiflow release [--push]            cut a release per the branching model
aiflow protect                     apply server-side branch protection (GitHub)
aiflow cost [...]                  token/cost baseline via ccusage
aiflow doctor                      check prerequisites + project summary
aiflow upgrade                     update the bundled toolchain
aiflow update                      self-update aiflow (git pull, or GitHub-release download if not a git checkout)
aiflow project-update               refresh THIS project (scripts incl. .github/scripts + agent defs
                                    + .githooks;
                                    customised files -> *.bak; .github/workflows never rewritten)
aiflow version

---

17. Token & cost optimisation

Set expectations first: token saving is a real goal, but aiflow's many quality rules (tests, coverage gates, static analysis, architect review) deliberately spend tokens on getting things right. The net win comes from not having to ask twice: a requirement that ships production-ready on the first pass needs no re-prompting and no rework — that saves more tokens (and time) than any output filter. The levers below then trim what's left:

• caveman — terse output mode (~75% fewer output tokens; code/commits/security stay normal). On by default.
• rtk — filters/compresses verbose command output before it enters context (60–90% fewer). On by default.
• Prefer full output? aiflow init --no-token-saving / aiflow change-settings --no-token-saving switches caveman + rtk off in one flag.
• graph + RAG retrieval — answer from graphify/cocoindex instead of reading whole files (~70% fewer).
• model routing — send easy/background steps to cheap or local (Ollama) models via aiflow shell --router.
• ponytail (off by default) — fewer tokens spent writing and reviewing code nobody needed in the first place; see §8.
• measure first — aiflow cost (ccusage) shows real spend so you optimise what matters.

---

18. CI/CD & building releases

• .github/workflows/ci.yml — validates the toolchain on push/PR: bash -n on all scripts, shellcheck (advisory), JSON validation of templates, PowerShell parse, and a dry-run build of the same Linux, macOS and Windows archives as the release workflow (all uploaded as artifacts).
• .github/workflows/release.yml — after CI succeeds for a push to main, if VERSION is a finished version without an existing GitHub Release, it builds per-OS archives (linux.tar.gz, macos.tar.gz, windows.zip + SHA256SUMS) and publishes the release.
• Projects also get .github/workflows/ci.yml (detects Node/Python/Go/Dart → format + tests) and .github/workflows/agent.yml (runs the Ralph loop in CI on manual dispatch, the agent issue label, or nightly; auth from ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repo secrets).

Build locally the same three platform archives CI and release use (requires zip):

bash .github/scripts/build-archives.sh

---

19. Project layout

your-project/
├─ .aiflow/
│  ├─ config.json            # the single source of truth (committed)
│  ├─ team-prefs.json        # shared team preferences (committed)
│  ├─ router-config.json     # generated: Ollama/cost providers (gitignored)
│  ├─ bd-close-sync.sh       # close → prompt push + Dolt-sync
│  ├─ next-task.sh           # next ready bead, ranked (queue mode)
│  └─ *.sh                   # audit/release/ralph helpers
├─ .beads/                   # Beads issue database (Dolt)
├─ .claude/
│  ├─ agents/  commands/     # subagents + slash commands
│  ├─ hooks/                 # caveman, formatter, beads-sync (SessionStart), queue-continue (Stop)
│  ├─ memory/                # project-aim, dev-environment, memory-policy
│  └─ settings.json          # permissions + hooks + MCP allow-list
├─ .githooks/                # commit-msg, pre-commit, pre-push (enforcement)
├─ docs/architecture/        # arc42 + ADRs
├─ .mcp.json                 # generated from config (host MCP, graphify, cocoindex, context7, …)
├─ AGENTS.md                 # operating rules every agent reads
└─ .env                      # secrets (gitignored, never global)

---

20. FAQ

Do I need an Anthropic API key? Either an API key or a Claude Code OAuth token (claude setup-token) — pick claude.auth at init.

Does it work offline / privately? Code indexing (cocoindex-code) and embeddings are local (no key). With Ollama you can run models locally too. Claude itself still calls Anthropic.

Is my data sent anywhere? Secrets stay in .env (gitignored, never global). Only what Claude needs for a request goes to Anthropic (or your local models via the router).

graphify vs cocoindex — do I need both? They're complementary: graphify answers structural questions exactly; cocoindex answers semantic/fuzzy ones cheaply. Both are recommended (§6).

How do I add another model? Ollama: aiflow ollama add <model>. Cloud: add it to ~/.claude-code-router/config.json and enable router (§12).

How do I use GitLab / Bitbucket / self-hosted instead of GitHub? aiflow change-settings → pick the remote type (or custom + base URL) → put the token in .env (§11).

Can several people work in one project? Yes — that's a core feature (§10): shared Dolt issue DB, atomic claim, session-start pull, pull-before-push.

How do I change my mind later? aiflow change-settings re-runs the Q&A and re-renders .mcp.json, hooks, branching, and memory from the new config.

Do I have to pre-install tools? No. The installer offers git/svn/ollama; aiflow install-deps (or aiflow init) installs the rest.

Something references the wrong git host / token? Re-run aiflow change-settings; check .env has the token env named in remote.tokenEnv; aiflow doctor shows the resolved config.

---

21. Troubleshooting

• jq is required — install jq (aiflow install-deps does). aiflow reads/writes config.json with it.
• bd/Dolt errors — aiflow install-deps installs both; bd dolt status checks the server.
• MCP server won't start — run aiflow doctor; check the tool is installed (ccc, graphify, Docker for the GitHub MCP) and the token env in .env matches remote.tokenEnv.
• Ollama models unused — enable router and run aiflow shell --router; confirm .aiflow/router-config.json lists your models and ollama list has them.
• Dolt sync conflict — bd dolt pull (merge), resolve, then bd dolt push. Never force-push.
• Report a bug — open an issue at https://github.com/Cyber93de/aiflow/issues with repro steps.

---

22. Credits & thanks

aiflow is glue. Enormous thanks to the projects it stands on — please star and support them:

• Claude Code (Anthropic) — the agent runtime everything builds on.
• Beads — Dolt-backed issue tracker; durable task memory across sessions.
• Dolt (DoltHub) — the versioned SQL database that makes team issue-sync work.
• graphify — the structural code knowledge graph over MCP.
• CocoIndex & cocoindex-code — the incremental, AST-aware semantic RAG index (ccc).
• Context7 (Upstash) — live, version-correct library docs over MCP.
• claude-task-master — goal/PRD → task tree.
• claude-code-router — model routing for cost/local models.
• Ollama — local model runtime (no API key).
• rtk — CLI-output filtering to cut context.
• ccusage — token/cost analytics.
• claude-code-templates — community agents/commands/MCPs/hooks.

Trademarks and projects belong to their respective owners; aiflow is an independent integration and is not affiliated with or endorsed by them.

---

23. Feedback, ideas & bug reports

This project lives on your input — and it's very welcome. Whether it's a rough idea, a feature wish, a "why does it work like that?", or straight-up criticism: bring it on. Honest feedback is how aiflow gets better.

• 💡 Ideas & suggestions — open a GitHub Discussion or an issue. No idea is too small or too wild.
• 🗣️ Criticism welcome — tell us what's confusing, clunky, or missing. Disagreement is useful.
• 🐛 Bug reports — open an issue with steps to reproduce, your OS, and the relevant aiflow doctor output. Small repro = fast fix.
• 🙌 Support — if aiflow helps you, a ⭐ on the repo, a shared link, or a kind word genuinely makes the day. Thank you for being here.

There is no paid tier and no donation ask — the best support is your feedback, a star, and telling a friend.

---

24. Contributing

Issues and PRs welcome at https://github.com/Cyber93de/aiflow. aiflow dogfoods itself: it uses Beads for its own tasks, Conventional Commits, and the CI workflow (bash -n, shellcheck, JSON + PowerShell validation) must pass. Keep changes project-scoped and secret-free.

---

25. License

MIT — Copyright (c) 2026 Cyber93de. See LICENSE.

aiflow vendors nothing — it installs/invokes external tools, each under its own license. See THIRD_PARTY_LICENSES.md for attribution.

---

Topics / keywords: Claude Code · Anthropic Claude · AI coding agent · agentic software delivery · MCP (Model Context Protocol) · Beads · Dolt · graphify · code knowledge graph · CocoIndex · cocoindex-code · semantic code search · RAG · Context7 · Ollama · local LLM · claude-code-router · rtk · caveman · ponytail · YAGNI · token optimization · Ralph loop · gitflow · Conventional Commits · GitHub · GitLab · Bitbucket · Forgejo · Gitea.  ·  Suggested GitHub repo topics: claude-code, anthropic, ai-agent, mcp, beads, rag, code-search, ollama, context7, rtk, caveman, ponytail, developer-tools, cli.