Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,13 @@ What actually happened instead.
**Logs**
If applicable, add logs from:
- Backbeat server output
- Claude Code console
- MCP client console
- Task logs (via TaskLogs tool)

**Environment:**
- OS: [e.g. macOS 14.0, Ubuntu 22.04]
- Node.js version: [e.g. 20.10.0]
- Claude Code version: [e.g. latest]
- MCP client & agent CLI version: [e.g. claude latest, codex 0.1]
- Backbeat version: [e.g. 0.5.0]

**Additional context**
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ npm run build
Backbeat uses [Vitest](https://vitest.dev/) with grouped test commands. The full suite is memory-intensive, so tests are split into safe groups:

```bash
# Safe to run from Claude Code or any environment
# Safe to run individually
npm run test:core # Core domain logic (~3s)
npm run test:handlers # Service handlers (~3s)
npm run test:services # Service layer (task-manager, recovery, etc.)
Expand Down
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@

## Why Backbeat Exists

**The Problem**: Claude Code is incredibly powerful, but you can only work on one thing at a time with a single claude code instance. This kills true multitasking and orchestration.
**The Problem**: AI coding agents are incredibly powerful, but you can only work on one thing at a time with a single instance. This kills true multitasking and orchestration.

**Our Belief**: AI should scale with your ambition, not limit it. Why use only one Claude instance?
**Our Belief**: AI should scale with your ambition, not limit it. Why use only one AI coding agent?

**The Vision**: Transform your machine or dedicated server into an AI powerhouse where you orchestrate multiple Claude Code instances through one main session. Work on authentication in repo A while simultaneously building APIs in repo B, all coordinated through your primary Claude Code interface - no context pollution, no workflow interruption.
**The Vision**: Transform your machine or dedicated server into an AI powerhouse where you orchestrate multiple AI coding agents through one main session. Work on authentication in repo A while simultaneously building APIs in repo B, all coordinated through your primary MCP client - no context pollution, no workflow interruption.

## Features

Expand All @@ -31,7 +31,7 @@ See **[FEATURES.md](./docs/FEATURES.md)** for complete feature list.

- Node.js 20.0.0+
- npm 10.0.0+
- Claude Code CLI installed (`claude` command available)
- An AI coding agent CLI installed (e.g., `claude`, `codex`, `gemini-cli`)

### System Requirements

Expand Down Expand Up @@ -61,13 +61,13 @@ Add to your project's `.mcp.json`:
}
```

Restart Claude Code to connect to Backbeat.
Restart your MCP client to connect to Backbeat.

## Usage

### MCP Tools

Once configured, use these tools in Claude Code:
Once configured, use these MCP tools:

| Tool | Description | Usage |
|------|-------------|-------|
Expand Down Expand Up @@ -325,11 +325,11 @@ See **[ROADMAP.md](./docs/ROADMAP.md)** for detailed plans and timelines.

## Troubleshooting

### Claude CLI not found
### Agent CLI not found

Ensure `claude` CLI is in your PATH:
Ensure your agent CLI is in your PATH:
```bash
which claude
which claude # or: which codex, which gemini
```

### Server won't start
Expand Down
10 changes: 5 additions & 5 deletions docs/FEATURES.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Last Updated: March 2026
## ✅ Core Task Delegation

### MCP Tools
- **DelegateTask**: Submit tasks to background Claude Code instances
- **DelegateTask**: Submit tasks to background AI agent instances
- **TaskStatus**: Check status of running/completed tasks
- **TaskLogs**: Retrieve stdout/stderr output from tasks (with tail option)
- **CancelTask**: Cancel running tasks with optional reason
Expand Down Expand Up @@ -82,9 +82,9 @@ Last Updated: March 2026

## ✅ Process Management

### Claude Code Integration
- **CLI Spawning**: Spawns `claude` processes with proper arguments
- **Permission Handling**: Uses `--dangerously-skip-permissions` flag
### Agent Process Management
- **CLI Spawning**: Spawns agent processes (`claude`, `codex`, `gemini`) with proper arguments
- **Permission Handling**: Agent-specific permission flags (e.g., `--dangerously-skip-permissions` for Claude)
- **Working Directory**: Supports custom working directories
- **Process Monitoring**: Tracks PIDs, exit codes, and resource usage

Expand Down Expand Up @@ -117,7 +117,7 @@ Last Updated: March 2026
- `beat help`: Show help and usage

### Direct Task Commands (v0.2.1+)
- `beat run <prompt>`: Delegate task directly to background Claude instance
- `beat run <prompt>`: Delegate task directly to a background agent instance
- `beat status [task-id]`: Check status of all tasks or specific task
- `beat logs <task-id>`: Retrieve task output and logs
- `beat cancel <task-id> [reason]`: Cancel running task with optional reason
Expand Down
18 changes: 10 additions & 8 deletions docs/SETUP_GUIDE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Backbeat Setup Guide for Claude Code
# Backbeat Setup Guide

## Quick Setup (2 minutes)

Expand Down Expand Up @@ -43,7 +43,7 @@ mkdir -p ~/.config/claude
cp /workspace/backbeat/config/mcp-config-ready.json ~/.config/claude/mcp_servers.json
```

### Step 3: Start NEW Claude Code Session
### Step 3: Start a New Coding Session

**Important**: Must be a NEW session, not `--continue`
```bash
Expand All @@ -56,7 +56,7 @@ claude "Let's test Backbeat MCP tools"

### Step 4: Test Integration

In the new Claude Code session, try:
In the new coding session, try:

1. **Check available tools**:
> "What MCP tools are available?"
Expand Down Expand Up @@ -96,12 +96,14 @@ npm install
npm run build
```

## Using Real Claude CLI
## Using a Real Agent CLI

To use with actual Claude CLI (not mock):
To use with an actual agent CLI (not mock):
To use with an actual agent CLI (not mock):

1. Remove `"MOCK_MODE": "true"` from config
2. Ensure `claude` CLI is installed
2. Ensure your chosen agent CLI is installed (e.g., `claude`, `codex`, `gemini-cli`)
3. Test with real tasks
3. Test with real tasks
Comment on lines +101 to 107
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicate lines introduced by this PR

The edit accidentally left both the old and new text. The paragraph intro appears twice (lines 101–102) and "3. Test with real tasks" is listed twice as consecutive step items (lines 106–107). The section should read:

Suggested change
To use with an actual agent CLI (not mock):
To use with an actual agent CLI (not mock):
1. Remove `"MOCK_MODE": "true"` from config
2. Ensure `claude` CLI is installed
2. Ensure your chosen agent CLI is installed (e.g., `claude`, `codex`, `gemini-cli`)
3. Test with real tasks
3. Test with real tasks
To use with an actual agent CLI (not mock):
1. Remove `"MOCK_MODE": "true"` from config
2. Ensure your chosen agent CLI is installed (e.g., `claude`, `codex`, `gemini-cli`)
3. Test with real tasks


## What You Can Do Now
Expand Down Expand Up @@ -140,8 +142,8 @@ npm run validate

## Success!

Once you see the tools in Claude Code, Backbeat is ready!
You can now delegate tasks to background Claude Code instances.
Once you see the tools in your MCP client, Backbeat is ready!
You can now delegate tasks to background AI agent instances.

---

Expand Down
8 changes: 5 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,17 @@
},
"keywords": [
"mcp",
"claude",
"claude-code",
"ai-agents",
"multi-agent",
"codex",
"gemini",
"automation",
"task-delegation",
"backbeat"
],
"author": "dean0x",
"license": "MIT",
"description": "Backbeat — MCP server for delegating tasks to background Claude Code instances",
"description": "Backbeat — MCP server for orchestrating background AI coding agents (Claude, Codex, Gemini)",
"publishConfig": {
"access": "public"
},
Expand Down
4 changes: 2 additions & 2 deletions src/adapters/mcp-adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -322,13 +322,13 @@ export class MCPAdapter {
tools: [
{
name: 'DelegateTask',
description: 'Delegate a task to a background Claude Code instance',
description: 'Delegate a task to a background AI agent instance',
inputSchema: {
type: 'object',
properties: {
prompt: {
type: 'string',
description: 'The task for Claude Code to execute',
description: 'The task for the AI agent to execute',
minLength: 1,
maxLength: 4000,
},
Expand Down
Loading