# Aiflow > One command turns any repo into a governed, AI-driven delivery pipeline for Claude Code: Beads task memory, code graph + semantic RAG, agents, Ollama, team sync, token savings. - **Type:** MCP server - **Install:** `agentstack add mcp-cyber93de-aiflow` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [cyber93de](https://agentstack.voostack.com/s/cyber93de) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [cyber93de](https://github.com/cyber93de) - **Source:** https://github.com/cyber93de/aiflow - **Website:** https://cyber93de.github.io/aiflow/ ## Install ```sh agentstack add mcp-cyber93de-aiflow ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # aiflow **aiflow turns any repository into a governed, AI-driven software-delivery pipeline with one command.** It wires [Claude Code](https://docs.claude.com/en/docs/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](https://cyber93de.github.io/aiflow/)** --- ## 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](https://cyber93de.github.io/aiflow/) — including **[AI Basics](https://cyber93de.github.io/aiflow/ai-basics)** (Claude Code, agents, memory, context windows, skills, hooks — in plain language) and a complete **[example-project walk-through](https://cyber93de.github.io/aiflow/example-project)** (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](https://nodejs.org) (LTS). Everything else aiflow can install for you. ### Windows (PowerShell) ```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) ```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) ```bash 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: ```bash 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](https://github.com/Cyber93de/aiflow/releases)**. --- ## 4. Build a first project (walk-through) ```bash 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` (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 **`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: ```bash # 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: ```text /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: ```bash 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](https://github.com/cyber93de) - **Source:** [cyber93de/aiflow](https://github.com/cyber93de/aiflow) - **License:** MIT - **Homepage:** https://cyber93de.github.io/aiflow/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-cyber93de-aiflow - Seller: https://agentstack.voostack.com/s/cyber93de - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.