fellowship-cli

v0.4.11

Published

2 days ago

🧙 Scaffold your AI development team

0High
0Medium
0Low

minigalaxymage

ai agents scaffold cli coding-agents dev-tools

⚔️ Fellowship

Your AI agents remember everything.

Fellowship is a CLI that turns AI coding agents into a team that learns. It orchestrates the full cycle: spec → code → review → learn → improve — so each run makes the next one better.

Works with Claude Code, Codex, and any CLI-based AI coding agent.

Why Fellowship?

AI coding agents are powerful but stateless. Every session starts from zero — they forget past decisions, repeat mistakes, and ignore project conventions.

Fellowship fixes this:

🧠 Persistent memory — Learnings, decisions, and gotchas survive between runs
📋 Auto-generated specs — Every task gets a detailed spec before coding starts
🛡️ Built-in code review — Sentinel (AI reviewer) catches bugs before you see the code
🔔 Notifications — Sounds, desktop alerts, and hooks when runs finish
🔀 Background runs — Agent works in isolation, you keep coding
👥 Team of specialists — Each agent has a role, profile, and memory
📊 Full traceability — Every run tracked with cost, duration, tokens, and decisions

Quick Start

# Install globally
npm install -g fellowship-cli

# New project
mkdir my-api && cd my-api && git init
fellowship init

# Existing project
cd my-existing-project
fellowship adopt

# Run a task
fellowship run "add user authentication with JWT"

# Run in background with human review
fellowship run "add rate limiting" --bg --review
# → You keep working → 🔊 notification → fellowship review

How It Works

You: fellowship run "add search endpoint"
                    │
                    ▼
           ┌──────────────┐
           │  Spec Engine  │ ← Generates detailed spec from task + learnings + gotchas
           └──────┬───────┘
                  │
                  ▼
           ┌──────────────┐
           │  Agent (Code) │ ← Claude Code writes code in isolated worktree
           └──────┬───────┘
                  │
                  ▼
           ┌──────────────┐
           │  🛡️ Sentinel  │ ← AI reviewer checks code against spec
           └──────┬───────┘
                  │
                  ▼
           ┌──────────────┐
           │ Human Review  │ ← You: accept, reject, or give feedback
           └──────┬───────┘
                  │
                  ▼
           ┌──────────────┐
           │  Learn & Push │ ← Extracts learnings, pushes branch, creates PR
           └──────────────┘

Key detail: Your working directory never changes. Fellowship creates an isolated git worktree for each run — you stay on your branch the whole time.

Commands

`fellowship init`

Interactive wizard that sets up Fellowship in a new project. Analyzes your description, generates architecture, creates an AI agent team, and scaffolds the project.

fellowship init

What it creates:

.fellowship/config.yaml — Project config (provider, model, settings)
.fellowship/team.yaml — Agent definitions (roles, skills, profiles)
.fellowship/profiles/ — Agent profiles with coding guidelines
.fellowship/architecture.md — Project architecture reference
.fellowship/fellowship.db — SQLite database (runs, decisions, learnings)
.gitignore — Auto-generated for your stack (Node, Java, Python, etc.)

`fellowship adopt`

Adds Fellowship to an existing project by analyzing the codebase. Detects stack, framework, patterns, and generates a team tailored to your project.

cd existing-project
fellowship adopt

`fellowship run <task>`

The core command. Generates a spec, assigns an agent, executes the task, reviews the code, and extracts learnings.

# Basic run
fellowship run "add pagination to GET /users"

# With human review (accept/reject/feedback)
fellowship run "refactor auth middleware" --review

# Run in background — free your terminal
fellowship run "add search endpoint" --bg

# Background + human review
fellowship run "add auth" --bg --review

# Preview what would happen (no code changes)
fellowship run "add search endpoint" --dry-run

# Skip AI review
fellowship run "fix typo in README" --no-review

# Use a pre-written spec
fellowship run --spec path/to/spec.md

Options: | Flag | Description | |------|-------------| | --bg | Run in background — free your terminal, get notified when done | | --review | Pause for human review after implementation | | --dry-run | Generate spec and show preview, no code changes | | --no-review | Skip the Sentinel AI review cycle | | --no-sanitize | Disable prompt injection sanitization | | --spec <path> | Use an existing spec instead of generating one | | --scribe | Force documentation generation after run | | --no-scribe | Skip documentation generation |

`fellowship run --bg`

Run in background — your terminal stays free while the agent works.

fellowship run "add user authentication" --bg

# ⚔️  Fellowship — running in background
#    Task:    add user authentication
#    PID:     45231
#    Log:     .fellowship/runs/run-1.log
#
#    fellowship log              ← view agent output
#    fellowship log --follow     ← stream in real time
#    fellowship status           ← check progress
#
# You'll hear a sound when it's done 🔊

When the run completes: sound + desktop notification + terminal flash. Use fellowship log to check output or fellowship review to accept/reject changes.

`fellowship log`

View the output log of a background run.

fellowship log                # latest run
fellowship log --follow       # stream in real time (tail -f)
fellowship log --run 3        # specific run number

`fellowship review`

Review changes from a background run. Accept or reject with full diff display.

fellowship review
# Shows diff, spec, stats
# [a]ccept  [r]eject  [d]iff  [s]pec

`fellowship spec <task>`

Generate a spec without running it. Useful for reviewing specs before execution.

fellowship spec "add WebSocket support for real-time updates"

`fellowship status`

Dashboard showing your team, recent runs, costs, and project stats.

fellowship status

⚔️  Fellowship v0.4.2 — my-api
   Provider: anthropic (claude-sonnet-4-6)

👥 Team (4 agents)
   ⚙️  Carlos — Backend development
   🗄️  Atlas — Database design and management
   🎯  Merlín — Project coordination
   🛡️  Sentinel — Code reviewer

📊 Recent Runs
   #   Task                          Agent    Status     Duration  Cost
   3   add rate limiting             Carlos   ✅ done    2m 15s   $0.31
   2   add CORS config               Carlos   ✅ done    1m 54s   $0.24
   1   scaffold project              Carlos   ✅ done    2m 50s   $0.67

📈 Summary
   Runs: 3 total (3 completed, 0 failed)
   Tokens: 892,411 (~$0.82)
   Learnings: 5 bullets (distilled)
   Decisions: 8 in DB

`fellowship learn <lesson>`

Manually add a learning to the project memory.

fellowship learn "Always use parameterized queries — never string interpolation for SQL"

`fellowship search <query>`

Search learnings and gotchas using FTS5 full-text search.

fellowship search "authentication"

`fellowship doctor`

Check your setup for issues. Verifies Node, Git, agent CLI, API key, config, team, Sentinel, learnings, and more. Zero LLM calls.

fellowship doctor

⚔️  Fellowship Doctor

  ✅ Node.js v25.6.1  (>= 18)
  ✅ Git 2.47.0
  ✅ Agent CLI  (claude)
  ✅ .fellowship/ directory
  ✅ config.yaml  (anthropic / claude-sonnet-4-6)
  ✅ team.yaml  (4 agents)
  ✅ API key  (configured for anthropic)
  ✅ Sentinel reviewer  (profile present)
  ✅ fellowship.db
  ✅ .gitignore  (covers fellowship.db)
  ⚠️  Learnings  (none yet — run some tasks first)
  ⚠️  Gotchas  (none yet)
  ✅ architecture.md

  All checks passed (11 ✅, 2 ⚠️, 0 ❌)

`fellowship sanitize`

Scan .fellowship/ files for prompt injection attempts.

fellowship sanitize

`fellowship scribe`

Generate or update project documentation (README, API docs, changelog).

fellowship scribe --readme
fellowship scribe --api
fellowship scribe --all

`fellowship memory`

Interactive TUI with four views: Dashboard, Runs, Memory, and Diff.

fellowship memory                      # Opens on dashboard
fellowship mem                         # Alias
fellowship memory --view runs          # Jump to runs table
fellowship memory --view memory --section gotchas  # Gotchas tab
fellowship memory --view diff          # Side-by-side diff
fellowship memory --view diff --diff main  # Diff against main
fellowship memory --search "database"  # Pre-filter memory entries

Views:

📊 Dashboard — stats overview: total runs, tokens, cost, team, last run
🏃 Runs — full run history table with agent, status, review, tokens, cost, duration
🧠 Memory — browse learnings, gotchas, decisions, reviews (4 sub-tabs)
📝 Diff — side-by-side diff view with add/remove coloring

Navigation: 1-4 jump to view, Tab cycle views, ↑↓/jk navigate, h/l switch memory tabs, Enter expand, / search, u/d page scroll (diff), q quit.

`fellowship connect`

Configure your AI provider credentials (stored securely in macOS Keychain / system credential store).

fellowship connect

`fellowship hire`

Add a new agent to your team through an AI conversation.

fellowship hire

Configuration

`.fellowship/config.yaml`

name: my-api
created: '2026-03-11'

ai:
  provider: anthropic
  model: claude-sonnet-4-6
  envVar: ANTHROPIC_API_KEY

# Code review settings
review:
  enabled: true                    # Enable/disable Sentinel (default: true)
  model: claude-haiku-4-5-20251001 # Cheaper model for reviews
  strictness: balanced             # strict | balanced | lenient
  maxCycles: 2                     # Max review-fix cycles

# Notifications & hooks
hooks:
  onComplete:
    - { sound: done }
    - { notify: desktop }
  onError:
    - { sound: error }
    - { notify: desktop }
  onReview:
    - { sound: review }
    - { notify: desktop }
  sounds: true                     # disable with false
  desktop: true                    # disable with false

# Documentation generation
scribe:
  enabled: false
  autoRun: false
  model: claude-haiku-4-5-20251001
  outputs: [changelog, readme]

# Learnings search
search:
  maxResults: 10
  minScore: 1.0
  autoIndex: true

# Security
security:
  sanitize: true
  strictMode: false
  logInjections: true

The Memory System

Fellowship maintains a persistent memory that grows with every run:

| File | Purpose | Updated | |------|---------|---------| | learnings.md | Raw lessons from each run | After every run | | learnings-distilled.md | Consolidated top learnings (max 30) | After every run | | gotchas.md | Technical pitfalls and warnings | After every run | | architecture.md | Project architecture reference | On init/adopt | | fellowship.db | Runs, decisions, tasks, events (SQLite + FTS5) | Continuously |

How memory improves runs:

Before generating a spec, Fellowship searches learnings via FTS5
Relevant learnings + all gotchas are injected as context
The spec includes a ## Context Considered section showing exactly what was used
After each run, new learnings are extracted and distilled

Skills System

Fellowship ships with built-in skills and supports project-level overrides:

fellowship/skills/          ← Built-in (shipped with CLI)
  code-review.md            ← Sentinel's review guidelines

.fellowship/skills/         ← Project overrides (optional)
  code-review.md            ← Your custom review guidelines

Project skills override built-in skills with the same name. Profiles reference skills with {{skill:name}}.

🔔 Notifications

Fellowship notifies you when runs complete — zero config required.

Built-in (automatic on all platforms):

| Platform | Sounds | Desktop Notifications | |----------|--------|-----------------------| | macOS | afplay (Glass, Basso, Ping) | osascript (native alerts) | | Linux | paplay / aplay (freedesktop sounds) | notify-send | | Windows | PowerShell SoundPlayer (tada, critical stop) | PowerShell toast notifications (Win10/11) |

Plus: terminal flash — colored bar on completion (green ✅ / red ❌ / yellow 🚫 / blue 👀).

Configurable hooks in config.yaml:

hooks:
  onComplete:
    - { sound: done }
    - { notify: desktop }
    - { notify: telegram }
    - "echo '$FELLOWSHIP_TASK completed' >> ~/fellowship.log"
  onError:
    - { sound: error }
    - { notify: desktop }
  onReview:
    - { sound: review }
    - { notify: desktop }
  sounds: true                # disable with false
  desktop: true               # disable with false
  telegramBotToken: "..."     # or env FELLOWSHIP_TELEGRAM_BOT_TOKEN
  telegramChatId: "..."       # or env FELLOWSHIP_TELEGRAM_CHAT_ID

Environment variables available in shell hooks:

| Variable | Example | |----------|---------| | FELLOWSHIP_TASK | "add user authentication" | | FELLOWSHIP_AGENT | "Carlos" | | FELLOWSHIP_STATUS | completed / failed / rejected | | FELLOWSHIP_BRANCH | feat/add-user-auth | | FELLOWSHIP_DURATION | 145 (seconds) | | FELLOWSHIP_TOKENS | 31000 | | FELLOWSHIP_COST | 0.47 | | FELLOWSHIP_PR_URL | https://github.com/.../pull/5 |

Supported notification providers:

Desktop — native OS notifications (zero config)
Telegram — set bot token + chat ID in config or env vars
Slack — set webhook URL in FELLOWSHIP_SLACK_WEBHOOK env var
Custom — any shell command with env vars

🛡️ Sentinel — The Built-in Reviewer

Every project gets Sentinel, a dedicated AI code reviewer. Unlike using another coding agent as reviewer, Sentinel has a specialized profile focused on:

Verifying acceptance criteria from the spec
Catching bugs and missing edge cases
Checking architecture compliance
Not nitpicking style or suggesting rewrites

Sentinel reviews every run automatically. Configure via review: in config.yaml.

Security

Fellowship includes prompt injection protection:

30+ detection patterns — XML tags, ChatML tokens, role markers, identity overrides, authority markers
Sanitization on every run — Learnings, gotchas, and architecture scanned before injection
fellowship sanitize — Manual scan with severity levels
Dry-run reports — --dry-run shows sanitization results before committing to a run
strictMode — Optional throw-on-detection for zero-tolerance environments

Supported Providers

| Provider | Agent CLI | Model | |----------|-----------|-------| | Anthropic | Claude Code | claude-sonnet-4-6, claude-opus-4-6 | | OpenAI | Codex | gpt-4o, o3-mini |

Platform Support

| Feature | macOS | Linux | Windows | |---------|-------|-------|---------| | Core CLI | ✅ | ✅ | ✅ | | Sounds | ✅ afplay | ✅ paplay/aplay | ✅ PowerShell | | Desktop notifications | ✅ osascript | ✅ notify-send | ✅ PowerShell toast | | Terminal flash | ✅ | ✅ | ✅ | | Keychain credentials | ✅ macOS Keychain | ✅ libsecret | ✅ Windows Credential Store | | Background runs | ✅ | ✅ | ✅ |

Requirements

Node.js >= 18
Git
A supported AI coding agent CLI installed (claude or codex)

License

MIT

Built with ⚔️ by MiniGalaxyMage

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

⚔️ Fellowship

Why Fellowship?

Quick Start

How It Works

Commands

fellowship init

fellowship adopt

fellowship run <task>

fellowship run --bg

fellowship log

fellowship review

fellowship spec <task>

fellowship status

fellowship learn <lesson>

fellowship search <query>

fellowship doctor

fellowship sanitize

fellowship scribe

fellowship memory

fellowship connect

fellowship hire