Cortex Documentation

A practical guide to setting up and using every component of Cortex — your personal agent infrastructure for tool creation, multi-agent coordination, session capture, and remote dispatch.

Quick Start

If you just want to get everything running as fast as possible, here are the six commands:

bash

# Check prerequisites
python3 --version  # Need 3.11+

# Clone and install
git clone https://github.com/zzhiyuann/cortex.git
cd cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# One-command setup (configures MCP, hooks, directories)
cortex init

# Start all services
cortex start

# Verify everything
cortex status

That's it. Restart Claude Code (if it was open) and you're ready.

What You'll Have

After these commands, four systems are active:

Forge available as MCP tools in Claude Code — create tools with natural language
Vibe Replay hooks capturing every Claude Code session automatically
A2A Hub ready for multi-agent coordination
Dispatcher accepting commands from your phone via Telegram

Tip

If you only want specific components, use the skip flags: cortex init --skip-dispatcher --skip-a2a. See Individual Components below.

Installation

Prerequisites

Requirement	Version	Why
Python	3.11+ (3.13 recommended)	Runtime for all components
Git	Any recent	Cloning repos, version control
Claude Code CLI	Latest	MCP integration (Forge), hooks (Vibe Replay)
Telegram account	—	Optional. Required only for Dispatcher
pip	23+	Package installation

Check your Python version:

bash

python3 --version
# Python 3.13.1  (good)
# Python 3.10.4  (too old -- upgrade first)

Note

On macOS, the system Python is often too old. Install a newer version with brew install python@3.13 or download from python.org.

Option A: Full Stack (Recommended)

This installs all four components and the cortex unified CLI:

bash

git clone https://github.com/zzhiyuann/cortex.git
cd cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Run interactive setup
cortex init

The cortex init command will:

Create virtual environments for each component
Register Forge and A2A Hub as MCP servers in ~/.mcp.json
Install Vibe Replay hooks into ~/.claude/settings.json
Create Dispatcher config at ~/.config/dispatcher/config.yaml
Prompt for your Telegram bot token and chat ID (optional, press Enter to skip)

Option B: Individual Components

Install only the parts you need:

bash

pip install forge-agent       # Just Forge
pip install a2a-hub            # Just A2A Hub
pip install vibe-replay        # Just Vibe Replay
pip install agent-dispatcher   # Just Dispatcher

Each package includes its own setup command:

bash

forge serve          # Starts Forge MCP server
vibe-replay install  # Installs Claude Code hooks
a2a-hub start        # Starts the hub
dispatcher init      # Interactive Dispatcher setup

Option C: From Source (Developer)

For contributing or modifying the code:

bash

# Clone all repos
git clone https://github.com/zzhiyuann/cortex.git
git clone https://github.com/zzhiyuann/forge.git
git clone https://github.com/zzhiyuann/a2a-hub.git
git clone https://github.com/zzhiyuann/vibe-replay.git
git clone https://github.com/zzhiyuann/dispatcher.git

# Install Forge in editable mode with dev dependencies
cd forge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cd ..

# Repeat for each component
cd a2a-hub
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cd ..

cd vibe-replay
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cd ..

cd dispatcher
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cd ..

Tip

Each component is a standalone Python project with its own pyproject.toml. The [dev] extra installs pytest, ruff, mypy, and other development tools.

Configuration

cortex init handles all configuration automatically. This section explains what it configures and how to customize things manually.

MCP Server Registry (~/.mcp.json)

This file tells Claude Code which MCP servers are available. Cortex registers Forge (for tool creation) and A2A Hub (for agent coordination):

json -- ~/.mcp.json

{
  "mcpServers": {
    "forge": {
      "command": "/path/to/forge/.venv/bin/forge-mcp"
    },
    "a2a-hub": {
      "command": "/path/to/a2a-hub/.venv/bin/a2a-hub",
      "args": ["bridge"]
    }
  }
}

Warning

The paths must be absolute, pointing to the actual venv binaries. If you move your installation directories, re-run cortex init or update these paths manually.

If you already have other MCP servers configured, cortex init merges the new entries — it does not overwrite your existing configuration.

Claude Code Hooks (~/.claude/settings.json)

Vibe Replay captures sessions through Claude Code's hook system. Two hooks are installed:

json -- ~/.claude/settings.json

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.vibe-replay/capture-hook.py  # vibe-replay"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.vibe-replay/stop-hook.py  # vibe-replay"
      }]
    }]
  }
}

PostToolUse fires after every tool call (file reads, edits, bash commands). The capture hook logs each event to the session file.
Stop fires when a Claude Code session ends. The stop hook finalizes the session — calculates statistics, detects phases, and writes the summary.

Note

The # vibe-replay comment at the end of each command is intentional — it lets cortex init and vibe-replay uninstall identify which hooks belong to Vibe Replay without disturbing your other hooks.

Dispatcher Config (~/.config/dispatcher/config.yaml)

This is the main configuration file for the Dispatcher. Every field has a sensible default, but you need to provide your Telegram credentials:

yaml -- ~/.config/dispatcher/config.yaml

# Telegram bot credentials
telegram:
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: YOUR_CHAT_ID

# Agent execution settings
agent:
  command: "claude"
  args: ["-p", "--dangerously-skip-permissions"]
  max_concurrent: 3        # Max tasks running at once
  timeout: 1800             # 30 min max per task
  max_turns: 50             # Max agent turns per task

# Polling and progress behavior
behavior:
  poll_timeout: 30          # Telegram long-poll interval (seconds)
  progress_interval: 180   # Send progress update every 3 min
  recent_window: 300       # "Recent" message window (5 min)
  cancel_keywords: ["cancel", "stop"]
  status_keywords: ["status"]

# Project routing
projects:
  myapp:
    path: ~/projects/myapp
    keywords: [myapp, app, frontend]
  api:
    path: ~/projects/api-server
    keywords: [api, backend, server]

Key settings explained:

agent.command / agent.args — The command Dispatcher uses to spawn Claude. The -p flag enables prompt mode (non-interactive). The --dangerously-skip-permissions flag lets the agent run without permission prompts (safe because Dispatcher controls the scope).
agent.max_concurrent — How many tasks can run simultaneously. Each task spawns a separate Claude process. Keep this low (2-3) to avoid hitting rate limits.
behavior.recent_window — If you send a short follow-up message within this window (default 5 min), Dispatcher treats it as a continuation of the previous task instead of a new one.
projects — Keyword-based routing. When your message contains a keyword, Dispatcher automatically sets the working directory to that project's path.

Using Forge — Create Tools with Natural Language

Forge turns plain-English descriptions into working, tested tools. It can generate MCP tools (usable in Claude Code), CLI commands, or Python modules.

From Claude Code (MCP)

After cortex init and restarting Claude Code, Forge is available as a set of MCP tools. In any Claude Code session, you can say things like:

"Create a tool that converts CSV files to JSON with column filtering"
"Build me a CLI that resizes images to thumbnails"
"Make an MCP tool that validates JWT tokens"

Claude Code will call Forge's forge_create MCP tool behind the scenes. Forge may ask clarification questions (through Claude Code's conversation), then generates, tests, and installs the tool.

Tip

When using Forge through Claude Code, the conversation is natural. You describe what you want, Forge asks follow-up questions, and you refine until the tool is right. No special syntax needed.

From the CLI

You can also use Forge directly from the command line:

bash

# Create a tool with full interactive pipeline
forge create "convert CSV to JSON with filtering"

# Create and install as CLI command
forge create "validate JWT tokens" --type cli --install cli

# Create as MCP tool and register it
forge create "resize images to thumbnails" --type mcp --install mcp

# Skip clarification questions (use defaults)
forge create "parse YAML config files" --no-clarify

Pipeline Steps

Every tool goes through this pipeline, whether you trigger it from Claude Code or the CLI:

Describe — You provide a plain-English description of what the tool should do. Be as specific or vague as you want.
Clarify — Forge asks questions to resolve ambiguity. What's the input format? How should errors be handled? What about edge cases? What dependencies are acceptable? You can skip this with --no-clarify.
Generate — Forge builds a ToolSpec (structured definition), then generates Python code from Jinja2 templates. It creates the main module, a CLI wrapper or MCP handler, and a requirements file.
Test — Forge auto-generates pytest test cases based on the ToolSpec and runs them in an isolated virtual environment. The tests cover normal usage, edge cases, and error paths.
Iterate — If tests fail, Forge reads the error output, diagnoses the issue, and regenerates the problematic code. This loop runs up to 5 times. Most tools pass on the first or second try.
Install — Places the finished tool where you specified:
- mcp → ~/.claude/mcp-tools/forge/{name}.py (available in Claude Code immediately)
- cli → ~/.local/bin/{name} (available in your PATH)
- local → ~/.forge/tools/{name}/ (saved for later use)

Managing Tools

bash

# List all tools Forge has created
forge list
# NAME             TYPE   INSTALLED   CREATED
# csv-to-json      mcp    mcp         2025-01-15
# jwt-validator    cli    cli         2025-01-16
# image-resizer    mcp    mcp         2025-01-17

# View a tool's source code
forge show csv-to-json

# Re-run tests for a tool
forge test csv-to-json

# Uninstall a tool (removes from install location + registry)
forge uninstall csv-to-json

What You'll Have

Working, tested tools that are immediately available in your workflow — as MCP tools in Claude Code, CLI commands in your terminal, or Python modules you can import. Every tool includes source code, tests, and documentation.

Using A2A Hub — Multi-Agent Coordination

A2A Hub is a coordination layer for multiple AI agents. Agents register with the hub, advertise their capabilities, and can discover and delegate tasks to each other.

Starting the Hub

bash

# Start everything (hub + bridge + dispatcher)
cortex start

# Or start just the hub
a2a-hub start

# Start on a specific port
a2a-hub start --host 0.0.0.0 --port 8080

# Check hub status
a2a-hub status

Creating an Agent

An agent is any process that connects to the hub and declares what it can do. Here's a complete example in Python:

python -- my_agent.py

from a2a_hub import Agent

# Create an agent with declared capabilities
agent = Agent("my-helper", capabilities=["summarize", "translate"])

@agent.on_task("summarize")
async def summarize(text: str, max_length: int = 200) -> dict:
    """Summarize the given text to max_length words."""
    words = text.split()[:max_length]
    return {
        "summary": " ".join(words),
        "original_length": len(text.split())
    }

@agent.on_task("translate")
async def translate(text: str, target: str = "en") -> dict:
    """Translate text to the target language."""
    # Your translation logic here
    return {"translated": text, "target": target}

# Connect to hub, register capabilities, and start listening
agent.run()

Run the agent:

bash

python3 my_agent.py
# Agent "my-helper" connected to hub
# Registered capabilities: summarize, translate
# Listening for tasks...

MCP Bridge Tools

The A2A Hub MCP bridge exposes six tools inside Claude Code. These let Claude Code interact with all connected agents:

MCP Tool	What It Does
`hub_status`	Shows all connected agents and their current state
`discover_agents`	Finds agents by capability (e.g., "summarize", "code-review")
`delegate_task`	Sends a task to a specific agent with parameters
`get_task_result`	Retrieves the result of a previously delegated task
`broadcast_message`	Sends a message to all connected agents
`list_tasks`	Shows task history with statuses

Example Workflow in Claude Code

Here's what a real multi-agent conversation looks like in Claude Code:

conversation

# You: "What agents are available?"
# Claude Code calls hub_status
# Response:
#   Connected agents: 3
#   - my-helper (summarize, translate)
#   - code-reviewer (review, lint)
#   - data-pipeline (etl, transform)

# You: "Ask the code reviewer to review this function"
# Claude Code calls discover_agents(capability="review")
# Then calls delegate_task(
#   agent_id="code-reviewer",
#   capability="review",
#   params={"code": "def calculate_total(items): ..."})
# Response: task_id="t-abc123", status="pending"

# You: "What did it say?"
# Claude Code calls get_task_result(task_id="t-abc123")
# Response: { "issues": [...], "suggestions": [...], "score": 8 }

What You'll Have

A network of specialized agents that can discover each other and collaborate through a central hub. Claude Code becomes an orchestrator — it finds the right agent for each task and delegates work automatically.

Using Vibe Replay — Session Capture & Wisdom

After cortex init, Vibe Replay is already running. Every Claude Code session is automatically captured in the background. You don't need to do anything — just use Claude Code normally.

Viewing Captured Sessions

bash

# List all captured sessions
vibe-replay sessions
# ID        PROJECT         DURATION   TOOLS   FILES   DATE
# abc123    cortex          42m        87      12      2025-01-20
# def456    webapp          18m        34       5      2025-01-19
# ghi789    api-server      1h 15m    142      28      2025-01-18

# Filter by project
vibe-replay sessions -p cortex

# Show last 10 sessions
vibe-replay sessions -n 10

# View terminal summary of a session (partial ID works)
vibe-replay show abc123
# Session abc123 -- cortex
# Duration: 42 minutes
# Phases: exploration (8m) -> implementation (22m) -> debugging (7m) -> testing (5m)
# Tools used: 87 (Read: 34, Edit: 28, Bash: 19, Grep: 6)
# Files modified: 12
# Key decisions:
#   - Chose asyncio over threading for the hub server
#   - Switched from REST to WebSocket for real-time agent communication

Generating HTML Replays

This is where Vibe Replay shines. It generates rich, interactive HTML documents from your session data:

bash

# Generate and open in browser
vibe-replay replay abc123

# Export to a specific file
vibe-replay export abc123 -f html -o replay.html

# Export as markdown
vibe-replay export abc123 -f markdown -o summary.md

# Export raw data as JSON
vibe-replay export abc123 -f json -o data.json

The HTML replay includes:

Interactive timeline with collapsible phases
Auto-detected phases: exploration, implementation, debugging, testing — with transitions highlighted
Key decisions and turning points called out
Code diffs shown inline with syntax highlighting
Statistics sidebar: tools used, files modified, duration breakdown
Dark/light theme toggle
Filterable events: show only code changes, or errors, or tool calls

Cross-Session Wisdom

Vibe Replay can analyze patterns across all your sessions to extract recurring lessons:

bash

# Aggregate learnings from all sessions
vibe-replay wisdom
# Common patterns:
#   - You tend to explore for 15-20% of session time before coding
#   - Most debugging sessions start with reading logs before code
#   - Test-first sessions have 40% fewer iteration cycles

# Analyze only the last 100 sessions
vibe-replay wisdom -n 100

# Re-analyze a specific session with updated logic
vibe-replay analyze abc123

What You'll Have

Every AI coding session automatically captured and transformed into structured knowledge — decisions, patterns, and lessons you can review, share, and learn from. Think of it as a flight recorder for your development process.

Using Dispatcher — Control from Your Phone

Dispatcher connects your Telegram to Claude Code. Send a message from your phone, and Dispatcher spawns an agent, routes it to the right project, and sends back the result.

Telegram Bot Setup

If you skipped this during cortex init, set it up now:

Create a Telegram bot. Open Telegram, find @BotFather, send /newbot. Follow the prompts to name your bot. BotFather gives you a bot token (looks like 7740709485:AAF35Lke...). Copy it.
Get your chat ID. Send any message to your new bot. Then visit this URL in a browser (replace YOUR_TOKEN with the actual token):
url
```
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
```
Look for "chat":{"id":123456789} in the JSON response. That number is your chat ID.

Configure Dispatcher:

bash

# Option A: use cortex init with flags
cortex init --telegram-token "YOUR_TOKEN" --telegram-chat-id YOUR_ID

# Option B: edit the config file directly
# vim ~/.config/dispatcher/config.yaml

Starting Dispatcher

bash

# Start with cortex (recommended -- starts hub + dispatcher)
cortex start

# Or start standalone
dispatcher start                # Foreground (see logs in terminal)
dispatcher start -d             # Detached (background)

# Install as a macOS LaunchAgent (starts on login, restarts on crash)
dispatcher install

# Remove the LaunchAgent
dispatcher uninstall

# Check status
dispatcher status

Tip

Using dispatcher install creates a macOS LaunchAgent that starts automatically on login and restarts if it crashes. This is the best option for always-on remote access.

Using from Telegram

Once Dispatcher is running, just send messages to your bot:

You Send	What Happens
`fix the login bug in webapp`	Routes to ~/projects/webapp, spawns Claude, fixes the bug
`add dark mode to the settings page`	Detects project from context, runs the task
`status`	Shows currently running tasks with elapsed time
`cancel`	Kills the currently running task
(short reply within 5 min)	Treated as follow-up to previous task

Note

Dispatcher only responds to messages from your configured chat_id. Other people messaging your bot will be ignored — no security risk even if your bot name is guessable.

Project Routing

Dispatcher uses keyword matching to figure out which project a task belongs to. Add your projects to the config:

yaml -- ~/.config/dispatcher/config.yaml

projects:
  webapp:
    path: ~/projects/webapp
    keywords: [web, frontend, webapp, ui, css]
  api:
    path: ~/projects/api-server
    keywords: [api, backend, server, endpoint, rest]
  docs:
    path: ~/projects/docs-site
    keywords: [docs, documentation, readme]
  infra:
    path: ~/projects/infra
    keywords: [deploy, infra, docker, ci, pipeline]

When you send "fix the frontend bug", Dispatcher sees "frontend" matches the webapp project, so it spawns the agent in ~/projects/webapp.

If no keywords match, Dispatcher will ask you to specify the project (or use a default if configured).

How Fire-and-Refine Works

Dispatcher uses a two-phase execution model to give you fast feedback:

Phase 1 (fast acknowledgment). The agent runs for 1 turn and sends a quick response to Telegram. This usually takes 10-30 seconds. You get immediate confirmation that the task was understood and work has started.
Phase 2 (full execution). If the task requires more work, the agent continues running in the background. Every 3 minutes (configurable via progress_interval), it sends a progress update to Telegram.
Result. When the agent finishes, the final output is sent to Telegram. If the task succeeded, you see a summary. If it failed, you see the error and what was attempted.

What You'll Have

Your phone becomes a remote control for AI coding agents. Send a message, the agent works in the background, and the result appears on your phone. You can be on the train, at a coffee shop, or in bed — and still ship code.

CLI Reference

cortex (unified)

The top-level command that manages all Cortex components:

bash

cortex init [--telegram-token TOKEN] [--telegram-chat-id ID]
            [--skip-dispatcher] [--skip-forge] [--skip-a2a] [--skip-replay]
cortex start           # Start all services (hub, bridge, dispatcher)
cortex stop            # Stop all services
cortex status          # Show status of all components
cortex doctor          # Verify all integrations and report issues
cortex --version       # Print version

forge

bash

forge create DESCRIPTION
      [--type mcp|cli|python]    # Output type (default: mcp)
      [--no-clarify]             # Skip clarification questions
      [--install mcp|cli|local]  # Where to install (default: local)
      [--max-iterations N]      # Max test-fix cycles (default: 5)

forge list                         # List all created tools
forge show NAME                    # View source code of a tool
forge test NAME                    # Re-run tests for a tool
forge uninstall NAME               # Remove a tool
forge serve                        # Start the MCP server (used by Claude Code)

a2a-hub

bash

a2a-hub start [--host HOST] [--port PORT]    # Start the hub server
a2a-hub bridge [--host HOST] [--port PORT]   # Start MCP bridge (for Claude Code)
a2a-hub status [--host HOST] [--port PORT]   # Show hub status
a2a-hub agents [--host HOST] [--port PORT]   # List connected agents
a2a-hub tasks [--host HOST] [--port PORT]    # List task history

vibe-replay

bash

vibe-replay install                # Install hooks into Claude Code settings
vibe-replay uninstall              # Remove hooks
vibe-replay status                 # Check if hooks are installed and working

vibe-replay sessions
      [-p PROJECT]               # Filter by project name
      [-n LIMIT]                 # Limit number of results

vibe-replay show SESSION_ID        # Terminal summary (partial ID works)
vibe-replay replay SESSION_ID      # Generate HTML replay and open in browser

vibe-replay export SESSION_ID
      [-f html|markdown|json]    # Export format (default: html)
      [-o OUTPUT]                # Output file path

vibe-replay analyze SESSION_ID     # Re-analyze a session
vibe-replay wisdom [-n LIMIT]     # Cross-session pattern analysis
vibe-replay serve [--host HOST] [--port PORT]  # Start web UI

dispatcher

bash

dispatcher init                    # Interactive setup (bot token, chat ID)
dispatcher start [-c CONFIG]       # Start in foreground
dispatcher start -d                # Start detached (background)
dispatcher install                 # Install macOS LaunchAgent (always-on)
dispatcher uninstall               # Remove LaunchAgent
dispatcher status                  # Check if running
dispatcher logs [-n LINES] [-f]   # View logs (-f for follow/tail)

Architecture & Concepts

The Four Layers

Cortex is organized into four layers, each handling a distinct concern:

Layer	Component	Purpose
Command	Dispatcher	Receives tasks from Telegram and routes them to the right project and agent
Communication	A2A Hub	Coordinates multiple agents — discovery, delegation, message passing
Creation	Forge	Generates new tools from natural language descriptions
Memory	Vibe Replay	Captures every session and extracts patterns and lessons

Each layer is independent — you can use any combination. But they work best together.

Data Flow

Here's how the components connect in a typical workflow:

The typical flow is:

You send a message from Telegram to Dispatcher.
Dispatcher identifies the project and spawns a Claude Code agent.
The agent can use Forge (via MCP) to create new tools if needed.
The agent can use A2A Hub (via MCP bridge) to delegate subtasks to specialized agents.
Throughout the session, Vibe Replay hooks capture every action, decision, and code change.
When done, Dispatcher sends the result back to Telegram.

Where Everything Lives

A summary of the key directories:

filesystem

# Configuration
~/.mcp.json                            # MCP server registry (Forge + A2A Hub)
~/.claude/settings.json                # Claude Code settings (Vibe Replay hooks)
~/.config/dispatcher/config.yaml       # Dispatcher configuration

# Data
~/.config/dispatcher/data/             # Dispatcher logs and task memory
~/.forge/tools/                        # Generated tools storage
~/.claude/mcp-tools/forge/             # MCP-installed tools (used by Claude Code)
~/.vibe-replay/sessions/               # Captured session data (JSON)

# Scripts (installed by vibe-replay)
~/.vibe-replay/capture-hook.py         # PostToolUse hook script
~/.vibe-replay/stop-hook.py            # Stop hook script

# Runtime
~/.cortex/                             # PID files and service logs
~/.cortex/hub.pid                      # A2A Hub process ID
~/.cortex/dispatcher.pid               # Dispatcher process ID
~/.cortex/logs/                        # Service log files

Troubleshooting

cortex status Shows a Component Not Found

This usually means the component wasn't installed or its virtual environment is missing.

bash

# Check what cortex status reports
cortex status
# Forge:      OK  installed, MCP registered
# A2A Hub:    ERR not found
# Vibe Replay: OK  hooks installed
# Dispatcher:  OK  running (PID 12345)

# Fix: re-run init for the missing component
cortex init

If a specific component's venv is corrupted, delete it and re-init:

bash

rm -rf /path/to/a2a-hub/.venv
cortex init

Forge MCP Not Showing in Claude Code

After running cortex init, you must restart Claude Code for MCP changes to take effect.

Verify the MCP config exists:
bash
```
cat ~/.mcp.json | python3 -m json.tool
```
You should see a "forge" key under mcpServers.
Verify the binary exists:
bash
```
ls -la /path/to/forge/.venv/bin/forge-mcp
```
If it doesn't exist, the Forge venv may need rebuilding.
Restart Claude Code completely (quit and reopen, not just a new session).

Warning

Simply opening a new Claude Code session is not enough. You need to fully quit and restart the Claude Code application for MCP server changes to load.

Vibe Replay Not Capturing Sessions

Check that hooks are installed:

bash

vibe-replay status
# Hooks: installed
# PostToolUse: OK
# Stop: OK
# Sessions directory: ~/.vibe-replay/sessions/ (23 sessions)

If hooks are missing:

bash

# Reinstall hooks
vibe-replay install

# Verify they appear in the settings file
cat ~/.claude/settings.json | python3 -m json.tool

If hooks are installed but sessions are empty, check the hook scripts exist:

bash

ls -la ~/.vibe-replay/capture-hook.py
ls -la ~/.vibe-replay/stop-hook.py

Dispatcher Not Responding to Telegram

Work through this checklist:

Is Dispatcher running?
bash
```
dispatcher status
# or
cortex status
```
Check the bot token. Open a browser and go to https://api.telegram.org/bot<TOKEN>/getMe. You should see your bot's info in the JSON response. If you get an error, the token is wrong.
Check the chat ID. Send a message to your bot, then visit https://api.telegram.org/bot<TOKEN>/getUpdates. Verify the chat.id matches your config.
Check logs:
bash
```
dispatcher logs -n 50 -f
```
Look for connection errors, authentication failures, or polling timeouts.

A2A Hub Bridge Can't Connect

The MCP bridge needs the hub to be running first:

bash

# Make sure the hub is running
a2a-hub status

# If not, start it
cortex start
# or
a2a-hub start

If the hub is running but the bridge can't connect, check that the host and port match:

bash

# The bridge defaults to localhost:8000
# If you started the hub on a different port:
a2a-hub bridge --port 8080

cortex doctor

When in doubt, run the diagnostic tool:

bash

cortex doctor
# Checking Python version...      OK  3.13.1
# Checking Claude Code CLI...     OK  installed
# Checking Forge installation...  OK  venv OK, MCP registered
# Checking A2A Hub...             OK  installed, hub reachable
# Checking Vibe Replay hooks...   OK  PostToolUse + Stop installed
# Checking Dispatcher...          OK  running, Telegram connected
# Checking file permissions...    OK  all OK
#
# All checks passed.

cortex doctor checks everything: Python version, CLI availability, venv integrity, MCP registration, hook installation, service connectivity, file permissions, and Telegram API reachability. It reports exactly what's wrong and how to fix it.

Environment Variables

These override the corresponding values in config files. Useful for CI, Docker, or temporary overrides:

Variable	Overrides	Default
`DISPATCHER_BOT_TOKEN`	`telegram.bot_token` in config.yaml	—
`DISPATCHER_CHAT_ID`	`telegram.chat_id` in config.yaml	—
`DISPATCHER_AGENT_COMMAND`	`agent.command` in config.yaml	`claude`
`DISPATCHER_MAX_CONCURRENT`	`agent.max_concurrent` in config.yaml	`3`
`DISPATCHER_TIMEOUT`	`agent.timeout` in config.yaml	`1800` (30 min)
`DISPATCHER_DATA_DIR`	Data directory path	`~/.config/dispatcher/data/`
`FORGE_TOOLS_DIR`	Where Forge stores generated tools	`~/.forge/tools/`
`VIBE_REPLAY_DIR`	Session storage directory	`~/.vibe-replay/sessions/`
`A2A_HUB_HOST`	Hub server host	`localhost`
`A2A_HUB_PORT`	Hub server port	`8000`

Example usage:

bash

# Override bot token for this session only
DISPATCHER_BOT_TOKEN="7740709485:AAF35..." dispatcher start

# Run hub on a different port
A2A_HUB_PORT=9000 a2a-hub start

File Locations Reference

A complete reference of every file and directory Cortex uses:

Configuration Files

Path	Purpose
`~/.mcp.json`	MCP server registry — tells Claude Code about Forge and A2A Hub
`~/.claude/settings.json`	Claude Code settings — contains Vibe Replay hooks
`~/.config/dispatcher/config.yaml`	Dispatcher settings — Telegram credentials, agent config, project routing

Data Directories

Path	Contents
`~/.forge/tools/`	All generated tools (source, tests, metadata)
`~/.claude/mcp-tools/forge/`	MCP-installed tools (symlinked from forge tools)
`~/.vibe-replay/sessions/`	Captured session data as JSON files
`~/.config/dispatcher/data/`	Dispatcher task logs and conversation memory
`~/.cortex/`	Service PID files and runtime logs
`~/.cortex/logs/`	Service log files (hub.log, dispatcher.log)

Scripts

Path	Purpose
`~/.vibe-replay/capture-hook.py`	PostToolUse hook — logs each tool call to the session file
`~/.vibe-replay/stop-hook.py`	Stop hook — finalizes session, calculates stats, writes summary

Tip

All these paths respect XDG conventions where applicable. If you have XDG_CONFIG_HOME set, Dispatcher will use $XDG_CONFIG_HOME/dispatcher/ instead of ~/.config/dispatcher/.

Cortex Documentation — Built for people who want to get things running, not read marketing copy.