@botanicastudios/code-team-runner

Code Team CLI

A simple oclif CLI app that reads the code-team.config.mjs file and sets up MCP (Model Context Protocol) configuration for Claude.

Features

• Reads agent configuration from code-team.config.mjs
• Supports flexible config loading: current directory first, then CLI directory fallback
• Creates a .code-team folder in the current working directory
• Generates an mcp.json file with MCP server configurations
• Loads system prompt files into environment variables (relative to config location)
• Prompts user for tasks
• Runs the Claude CLI with appropriate arguments

Installation

• Install dependencies:

npm install

• Build the project:

npm run build

• Make the CLI globally available (optional):

npm link

Usage

Basic Usage

./bin/run.js create

or if you have linked it globally:

code-team create

With Task Flag

./bin/run.js create --task "Create a new React component"

Reset Context

By default, the CLI continues previous conversation context. To start fresh:

./bin/run.js create --reset-context --task "Start a new project"

Debug Mode

By default, the CLI only shows the formatted conversation between agents. To see setup and configuration messages:

./bin/run.js create --debug --task "Create a component"

Help

./bin/run.js create --help

Configuration Loading

The CLI looks for code-team.config.mjs in this order:

• Current directory: Where you run the CLI from
• CLI directory: Fallback to the directory where the CLI is installed

This allows you to:

• Use a project-specific config by placing code-team.config.mjs in your project directory
• Use the default config that ships with the CLI if no local config exists

Important: System prompt files are resolved relative to whichever directory the config file was found in.

How It Works

• Config Reading: Looks for code-team.config.mjs in current directory, then CLI directory
• Directory Setup: Creates .code-team/ directory in the current working directory
• MCP Configuration: Generates mcp.json with agent configurations:
  • Each agent from the config becomes an MCP server
  • System prompts are loaded from files (relative to config location) and stored in environment variables
  • The start script path points to ./claude-code-mcp/start.sh (relative to config location)
• Prompt Loading: Loads launch agent system prompts
• Task Input: Prompts user for a task (unless provided via --task flag)
• Claude Execution: Runs Claude with:
  • --verbose
  • --output-format stream-json
  • --mcp-config ./.code-team/mcp.json
  • --dangerously-skip-permissions
  • --continue (unless --reset-context flag is used)
  • System prompts (if provided)
  • The user's task

MCP Configuration Format

The generated mcp.json follows this structure:

{
  "mcpServers": {
    "agent_name": {
      "type": "stdio",
      "command": "/absolute/path/to/config-location/claude-code-mcp/start.sh",
      "args": [],
      "env": {
        "TOOL_NAME": "agent.toolName",
        "WORKSPACE": "/absolute/path/to/invocation/directory",
        "SYSTEM_PROMPT": "content of system prompt file",
        "MODEL": "agent.model"
      }
    }
  }
}

Environment Variables

Each MCP server receives these environment variables:

• TOOL_NAME (required): The tool name from the agent configuration
• WORKSPACE (required): The absolute path to the directory where the CLI was invoked
• SYSTEM_PROMPT (optional): Content of the system prompt file, if specified
• APPEND_SYSTEM_PROMPT (optional): Content of the append system prompt file, if specified
• MODEL (optional): The model name, if specified in the agent configuration

Note: SYSTEM_PROMPT, APPEND_SYSTEM_PROMPT, and MODEL are only included when they have actual values.

The MCP configuration file is created at ./.code-team/mcp.json in your current working directory.

Requirements

• Node.js 18+
• Claude CLI installed and available in PATH
• code-team.config.mjs file (either in current directory or ships with CLI)
• System prompt files referenced in config (relative to config location)

Development

Run in development mode:

npm run dev create

Example code-team.config.mjs

export default {
  launchAgent: {
    name: "project_manager",
    description: "Project Manager",
    toolName: "task_project_manager",
    root: true,
    systemPromptFile: "./system-prompts/project_manager.md",
  },
  agents: [
    {
      name: "qa_specialist",
      description: "QA Specialist",
      toolName: "task_qa_specialist",
      systemPromptFile: "./system-prompts/qa_specialist.md",
    },
    {
      name: "software_architect",
      description: "Software Architect",
      toolName: "task_software_architect",
      systemPromptFile: "./system-prompts/software_architect.md",
      model: "opus",
    },
    {
      name: "developer",
      description: "Developer",
      toolName: "task_developer",
      model: "sonnet",
    },
  ],
};

Local vs Global Configuration

Using a Local Config

Create a code-team.config.mjs in your project directory to override the default configuration:

# In your project directory
echo 'export default { /* your config */ };' > code-team.config.mjs
code-team create

The CLI will use your local config and resolve system prompt files relative to your project directory.

Using the Default Config

If no local config exists, the CLI will use the default configuration that ships with it:

# From any directory without code-team.config.mjs
code-team create

The CLI will use the default config and resolve system prompt files relative to the CLI installation directory.

Enhanced Output Formatting

The CLI provides a beautifully formatted view of the conversation between your Project Manager and the different agents, with colors optimized for both dark and light terminal backgrounds.

Output Modes

• Default: Shows only the formatted agent conversation (clean, focused view)
• Debug (--debug): Shows setup messages plus the formatted conversation

Message Types

• 🚀 Session Started - Shows connected agents and session info
• 🎯 Project Manager - Messages from the launch agent to you
• 📤 Requesting [Agent] - When the Project Manager asks one of your defined agents to do something (filters out regular Claude tools)
• 📥 Agent Response - Replies from agents and tools
• ✅ Task Completed - Final summary with stats (duration, cost, turns)

Debug Output

When using --debug, you'll also see:

• Configuration file discovery
• Directory creation in current working directory
• System prompt loading
• MCP configuration writing to ./.code-team/mcp.json
• Command execution details

Example Output

🚀 Session Started
   Session ID: 1cc222fd-6efd-49af-81a7-6f07f4c1449f
   Connected Agents: developer (connected), software_architect (connected), qa_specialist (connected)

🎯 Project Manager:
   I'll help you create a Hello World Node.js script. Let me analyze the requirements...

📤 Requesting Software Architect:
   Create a simple PRD (Product Requirements Document) for a Hello World Node.js script...

📥 Agent Response:
   I've created the PRD and TODO list. The implementation tasks are now tracked...

📤 Requesting Developer:
   Please implement the Hello World Node.js script based on the PRD and TODO list...

📥 Agent Response:
   Created `hello.js` - run with `node hello.js` to see "Hello World" output.

✅ Task Completed Successfully!
   Duration: 65s
   Cost: $0.0794
   Turns: 7

This formatted output makes it easy to follow the multi-way conversation and understand how your team of AI agents collaborates to complete tasks.