Skip to main content
Glama

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.

Related MCP server: CHARLIE

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

Available Tools

5 tools
guideA

Access project guide documents. (list/read)

  • list: Show available guides (excludes _-prefixed required guides).

  • read: Read a specific guide by topic name.

Required guides (_plan.md, _session_*.md, etc.) are auto-loaded by corresponding tools. Regular guides: When a guide name matches the current task context, proactively read it without waiting for the user to ask.

Inputs: topic, action, session.

initA

Initialize aidflow in the current project.

Creates .aidflow/ directory, config, guides, and Claude Code skills (.claude/skills/). Call this once when first using aidflow in a project. If already initialized, returns current status (use force: true to overwrite).

Inputs: force.

planA

Manage session work plans. (create/get)

  • create: Start a structured planning workflow. Guides through requirements gathering (HITL via AskUserQuestion), codebase research, and writing a comprehensive plan.md (PRD + implementation plan). The plan serves as the final execution specification before coding.

  • get: Read existing plan and show progress (checkbox-based).

Optional - skip for simple bug fixes. Use for medium/large tasks that benefit from upfront planning.

Inputs: action, session.

select_serviceA

Select target service in multi-service workspace. (list/select/status)

  • list: Discover all .aidflow directories in workspace. Auto-selects if only one found.

  • select: Select a specific service by name. Optionally bind to a session for parallel work.

  • status: Show current service selection (session-bound or global).

Call this before other tools (session, plan, guide) when working in a multi-service workspace. Single-service projects are auto-selected on list.

Inputs: action, service, session, workspacePath.

sessionA

Manage development sessions. (create/list/status/complete)

  • create: Start a new session. Optionally creates a git worktree for isolation.

  • list: Show all active sessions with their status.

  • status: Get session progress (changed files, plan progress, next suggestion).

  • complete: Archive session to history. Prompts for worktree cleanup.

Start with create when beginning work, end with complete when done.

Inputs: action (required), name, force, worktree.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    All five tools have clearly distinct purposes: guide for reading documents, init for project setup, plan for work plans, select_service for multi-service selection, and session for development sessions. No overlap in functionality.

    Naming Consistency4/5

    Most tool names are single lowercase verbs (guide, init, plan, session), which is consistent. However, 'select_service' breaks this pattern by using an underscore and a verb_noun structure, creating minor inconsistency.

    Tool Count5/5

    With 5 tools, the server is well-scoped. Each tool addresses a core aspect of the development workflow without being too numerous or too sparse.

    Completeness4/5

    The tool set covers the main lifecycle (init, plan, session, guide reading) with appropriate actions. Minor gaps like no explicit update for plans or deselect for service are acceptable for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers