aidflow

Session-based development workflow MCP server for Claude Code.

Every development task gets its own session with a plan, progress tracking, and archiving. Claude Code automatically resumes where you left off, even in new conversations.

Installation

npm install -g aidflow

Add to your Claude Code MCP configuration (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "aidflow": {
      "command": "aidflow",
      "env": {
        "AIDFLOW_ROOT": "/path/to/your/project"
      }
    }
  }
}

Or run with npx (no install):

{
  "mcpServers": {
    "aidflow": {
      "command": "npx",
      "args": ["-y", "aidflow"],
      "env": {
        "AIDFLOW_ROOT": "/path/to/your/project"
      }
    }
  }
}

AIDFLOW_ROOT defaults to process.cwd() if not set.

What It Does

aidflow structures your Claude Code workflow into sessions - isolated units of work with plans, progress tracking, and completion reports.

Development Cycle

init -> /spec -> session create -> plan create -> work -> /review -> session complete -> /report

1. init - Set up .aidflow/ directory and configuration
2. /spec - Define project engineering foundations (SPEC.md)
3. session create - Start a new work session
4. plan create - Structured planning with multi-round requirements gathering
5. Work - Implement using Claude Code's native tools, following the plan
6. /review - Quality gate before completing
7. session complete - Archive the session to history
8. /report - Generate a completion report

Context Recovery

When you start a new conversation, aidflow automatically detects active sessions and resumes where you left off - reading the plan, checking progress, and continuing work without losing context.

Git Worktree Support

Each session can optionally create a git worktree, giving you an isolated branch for the work. Useful for parallel tasks.

Tools

Tool	Actions	Description
init	-	Initialize aidflow in a project
session	create, list, status, complete	Manage development sessions
plan	create, get	Create and track work plans
guide	list, read	Access project-specific guide documents

Skills

Installed to .claude/commands/ during init:

Skill	Description
/spec	Create or update SPEC.md (project conventions)
/review	Quality review before session complete
/report	Generate completion report after archiving

Project Structure

After init, your project gets:

your-project/
  SPEC.md                    # Project engineering foundations (via /spec)
  .aidflow/
    config.yaml              # Configuration
    README.md                # Internal documentation
    sessions/                # Active sessions
      {name}/
        meta.json            # Session metadata
        plan.md              # Work plan (optional)
    history/                 # Archived sessions
      YYMMDD_{name}/
        meta.json
        plan.md
        report.md
    guides/                  # Project-specific guides
    worktrees/               # Git worktrees (gitignored)
  .claude/
    commands/                # Claude Code skills
      spec.md
      review.md
      report.md

Configuration

.aidflow/config.yaml:

version: 1

worktree:
  auto: false                # Auto-create worktree per session
  path: ".aidflow/worktrees"
  branch_prefix: ""          # e.g., "feature/", "fix/"

session:
  history_path: ".aidflow/history"
  date_format: "YYMMDD"     # or "YYYYMMDD"

guides:
  path: ".aidflow/guides"

Requirements

• Node.js >= 22
• Claude Code (or any MCP-compatible AI client)

License

MIT