Documentation

Complete reference for the Shazam CLI, configuration, and API.

Prerequisites

Before installing Shazam, ensure you have the following tools and accounts set up.

💧

Elixir>= 1.16required

Shazam is built on Elixir/OTP. Erlang/OTP, SQLite (via Exqlite), and standard build tools come bundled with the Elixir installation. Install via asdf, mise, or your system package manager.

Install guide →

🦀

Rust>= 1.70required

Required for the TUI terminal interface. Install via rustup.

Install guide →

🤖

Claude Code CLIrequired

Shazam uses Claude Code to run AI agents. Install and configure with your Anthropic API key.

Install guide →

Installation & Setup

Get Shazam running in under 5 minutes with these steps.

1. Clone the repository

git clone https://github.com/raphaelbarbosaqwerty/shazam-cli.git && cd shazam-cli

2. Install Elixir dependencies

mix deps.get

3. Build the project

./build.sh

Builds the Elixir escript and compiles the Rust TUI binary. Installs both to ~/bin/.

4. Initialize your project

shazam init

Creates a shazam.yaml with the interactive wizard — choose your company name, mission, and team template.

5. Open the interactive shell

shazam shell

Launches the Rust-powered TUI with real-time events, overlays, and ghost text autocomplete. This is the primary way to use Shazam.

Interactive Shell

The interactive shell is the primary way to use Shazam. It provides a Rust-powered TUI with real-time events, overlays, and ghost text autocomplete.

Core Commands

/startStart the orchestrator and begin processing tasks

/stopStop the orchestrator and all running agents

/pausePause the orchestrator — agents finish current work but pick up no new tasks

/resumeResume a paused orchestrator

/statusShow system status including agents, tasks, and RalphLoop state

Task Management

/tasksOpen the tasks overlay — browse, filter, and act on all tasks

/task <title>Create a new task with the given title

/approve [id]Approve a pending subtask in the approval queue

/aaApprove all pending subtasks at once

/reject <id>Reject a pending subtask with an optional reason

Task Actions (via /tasks overlay → Enter)

/pause-task <id>Pause a running task

/resume-task <id>Resume a paused task

/kill-task <id>Kill a running task immediately

/retry-task <id>Retry a failed or killed task

/delete-task <id>Delete a task from the board permanently

Agent Management

/agentsList all agents with their roles, status, and budget

/agent add <name>Add a new agent interactively

/agent edit <name>Edit an existing agent configuration

/agent remove <name>Remove an agent from the company

/agent presetsBrowse available agent preset templates

Team Templates

/team create <domain>Create a new team from a domain template

/team templatesList all available team templates

Views & Navigation

/dashboardOpen the live dashboard with agent status and metrics

/configView current shazam.yaml configuration

/orgDisplay the agent hierarchy tree

/helpShow all available commands and shortcuts

/clearClear the event log in the shell

Communication

/msg <agent> <message>Send a direct message or instruction to a specific agent

/auto-approve [on|off]Toggle automatic approval of PM-created subtasks

Exit

/quitExit the interactive shell

/exitExit the interactive shell (alias for /quit)

Keyboard Shortcuts

↑ / ↓Navigate command history

TabAccept ghost text autocomplete

PgUp / PgDnScroll the event log

Mouse scrollScroll events

EnterOpen action menu (in /tasks overlay)

Ctrl+CExit the shell

ESCClose current overlay

CLI Commands

Shazam provides Mix tasks for managing your AI agent orchestrator. All commands follow the mix shazam.<command> pattern.

`shazam init`

Create a new shazam.yaml configuration with an interactive wizard. Prompts for company name, mission, and team template.

Usage

mix shazam.init

Examples

Run the interactive setup wizard

mix shazam.init

`shazam start`

Boot the orchestrator server and create the company from shazam.yaml. Starts the OTP supervision tree, TaskBoard, SessionPool, and RalphLoops.

Usage

mix shazam.start [options]

Flags

-p, --portServer port for the HTTP API (default: 4040)

-f, --filePath to YAML config file (default: .shazam/shazam.yaml)

--no-resumeSkip automatic RalphLoop resume on startup

Examples

Start with default settings

mix shazam.start

Start on a custom port with a specific config

mix shazam.start -p 5000 -f my-team.yaml

Start without resuming previous tasks

mix shazam.start --port 4040 --no-resume

`shazam stop`

Stop a running company by sending an HTTP request to the running server instance.

Usage

mix shazam.stop [options]

Flags

-c, --companyName of the company to stop (default: auto-detected)

-p, --portServer port to connect to (default: 4040)

--allStop all running companies at once

Examples

Stop the auto-detected company

mix shazam.stop

Stop a specific company by name

mix shazam.stop -c MyCompany

Stop all running companies

mix shazam.stop --all

`shazam status`

Display current system status including company mission, agent table (name, role, status, domain, budget), RalphLoop status, task summary, and token usage.

Usage

mix shazam.status [options]

Flags

-c, --companyShow status for a specific company only (default: all companies)

Examples

Show status for all companies

mix shazam.status

Show status for a specific company

mix shazam.status -c MyTeam

`shazam task`

Create a new task in a running company. The task is added to the TaskBoard and automatically assigned based on role and availability.

Usage

mix shazam.task <title> [options]

Flags

-t, --toAssign task to a specific agent by name (default: auto-assigned)

-c, --companyTarget company name (default: auto-detected)

-d, --descriptionAdditional task description or details

Examples

Create a simple task

mix shazam.task "Implement user authentication"

Assign to a specific agent in a company

mix shazam.task "Fix login bug" --to senior_dev -c MyTeam

Create a task with a detailed description

mix shazam.task "Write tests" -t qa -d "Full coverage required"

`shazam org`

Display the agent hierarchy tree for a company, showing the chain of command from top-level agents down.

Usage

mix shazam.org [options]

Flags

-c, --companyCompany name to display (default: auto-detected)

Examples

Show the org chart

mix shazam.org

Show org chart for a specific company

mix shazam.org -c MyTeam

`shazam logs`

Stream live agent output and events in real-time. Supports filtering by agent name, company, or domain.

Usage

mix shazam.logs [agent_filter] [options]

Flags

-c, --companyFilter logs by company name

-d, --domainFilter logs by agent domain

Examples

Stream all agent logs

mix shazam.logs

Stream logs for a specific agent

mix shazam.logs senior_dev

Filter by domain and company

mix shazam.logs -d backend -c MyCompany

`shazam agent.add`

Dynamically add a new agent to a running company without restarting. Supports presets for quick setup.

Usage

mix shazam.agent.add <agent_name> [options]

Flags

-n, --nameAgent name (alternative to positional argument)

-r, --roleAgent role or title

-s, --supervisorName of the supervising agent

-d, --domainDomain or module ownership area

-b, --budgetToken budget for the agent (default: 100000)

-m, --modelAI model to use (e.g., claude-opus-4-1)

-c, --companyTarget company name (default: auto-detected)

--presetUse a preset template (e.g., senior_dev, qa, pm)

Examples

Add a designer agent with a supervisor

mix shazam.agent.add designer --role "UI Designer" --supervisor pm --budget 80000

Add a QA engineer reporting to PM

mix shazam.agent.add qa_engineer -r "Senior QA" -s pm

Add an agent from a preset template

mix shazam.agent.add researcher --preset market_analyst

`shazam apply`

Reconcile the running state with shazam.yaml. Creates or updates the company to match the current configuration file.

Usage

mix shazam.apply [options]

Flags

-f, --filePath to YAML config file (default: .shazam/shazam.yaml)

Examples

Apply the default config file

mix shazam.apply

Apply a specific config file

mix shazam.apply -f custom-team.yaml

`shazam dashboard`

Launch a live TUI dashboard with agent status, budget bars, task counts, RalphLoop status, and event log. Press q to quit, r to refresh.

Usage

mix shazam.dashboard [options]

Flags

-c, --companyCompany to display in the dashboard (default: auto-detected)

Examples

Launch the dashboard

mix shazam.dashboard

Launch dashboard for a specific company

mix shazam.dashboard -c MyTeam

Configuration

Shazam is configured via a shazam.yaml file at the root of your project.

shazam.yaml example

company:
  name: "my-project"
  mission: "Build great software"

agents:
  - name: pm
    role: "Project Manager"
    model: "claude-haiku-4-5-20251001"
    budget: 100000
    supervisor: null
    tools: [Read, Edit, Write, Bash, Grep, Glob]
    domain: "management"

  - name: senior_dev
    role: "Senior Developer"
    model: "claude-sonnet-4-20250514"
    budget: 150000
    supervisor: pm
    tools: [Read, Edit, Write, Bash, Grep, Glob]
    domain: "backend"
    modules: ["lib/core", "lib/api"]

  - name: qa
    role: "QA Engineer"
    model: "claude-sonnet-4-20250514"
    budget: 100000
    supervisor: pm
    tools: [Read, Bash, Grep, Glob]
    domain: "testing"

config:
  auto_approve: false
  auto_retry: true
  max_concurrent: 4
  max_retries: 2
  poll_interval: 5000
  module_lock: true
  peer_reassign: true

Configuration Fields

company.name

Company name identifier(string)

company.mission

Mission statement for the company(string)

agents[].name

Agent identifier used in CLI commands and task assignment(string)

agents[].role

Agent role/title (e.g., pm, senior_dev, qa)(string)

agents[].model

AI model for this agent(string)— default: claude-haiku-4-5-20251001

agents[].budget

Token budget for the agent(integer)— default: 100000

agents[].supervisor

Name of the supervising agent (null for top-level)(string | null)

agents[].tools

Available tools: Read, Edit, Write, Bash, Grep, Glob, WebSearch(list[string])

agents[].domain

Module ownership area for module locking(string)

agents[].skills

Assigned skill memory files(list[string])

agents[].modules

Owned code modules for exclusive access(list[string])

agents[].system_prompt

Custom system prompt override for this agent(string)

config.auto_approve

Skip approval queue for PM-created subtasks(boolean)— default: false

config.auto_retry

Automatically retry failed tasks with exponential backoff(boolean)— default: false

config.max_concurrent

Maximum agents working simultaneously (1-10)(integer)— default: 4

config.max_retries

Default retry attempts per failed task(integer)— default: 2

config.poll_interval

Task polling interval in milliseconds(integer)— default: 5000

config.module_lock

Prevent concurrent edits to same code module(boolean)— default: true

config.peer_reassign

Allow idle agents to pick up tasks from busy peers(boolean)— default: true

Agent Roles & Presets

Shazam ships with 10 pre-configured agent presets. Each preset defines default tools, model, and behavior.

📋pm

Project Manager — breaks down tasks, creates subtasks, coordinates team

👨‍💻senior_dev

Senior Developer — implements features, handles complex code changes

👩‍💻junior_dev

Junior Developer — handles simpler tasks, learns from senior feedback

🧪qa

Quality Assurance — writes tests, validates implementations, finds bugs

🎨designer

Designer — UI/UX work, CSS, component styling, visual consistency

🔍researcher

Researcher — investigates solutions, explores APIs, gathers information

🔧devops

DevOps — CI/CD pipelines, deployment, infrastructure configuration

✍️writer

Technical Writer — documentation, READMEs, API docs, guides

📊market_analyst

Market Analyst — market research, competitive analysis, business insights

🕵️competitor_analyst

Competitor Analyst — tracks competitors, identifies opportunities

REST API

Shazam exposes a REST API via Bandit/Plug for task management and monitoring.

GET/api/status

Get overall orchestrator status including all companies and agents.

GET/api/companies

List all registered companies with their agent counts and task stats.

GET/api/companies/:id/tasks

List all tasks for a specific company with filtering support.

POST/api/tasks

Submit a new task to the orchestrator. Accepts JSON body with title, description, role, and priority.

GET/api/tasks/:id

Get detailed information about a specific task including status, assignee, and results.

DELETE/api/tasks/:id

Cancel a pending or in-progress task.

POST/api/approval/:id/approve

Approve a pending subtask in the human-in-the-loop queue.

POST/api/approval/:id/reject

Reject a pending subtask with an optional reason.

GET/api/metrics

Get agent performance metrics including task counts, durations, and success rates.

WS/ws

WebSocket endpoint for real-time event streaming (task updates, agent status, logs).

Architecture

Shazam is built on Elixir/OTP, leveraging GenServer, ETS, and DynamicSupervisor for fault-tolerant agent management.

Core Modules

ApplicationOTP supervision tree, boots all subsystems on startup

OrchestratorParallel and pipeline agent execution via Claude Code SDK

CompanyGenServer managing agent hierarchy, tasks, and company lifecycle

RalphLoopPer-company polling loop for task picking and execution

TaskBoardETS-backed task CRUD with atomic checkout (pending → in_progress → completed)

TaskExecutorBuilds prompts, manages sessions, executes tasks via Claude Code

TaskSchedulerTask selection, peer reassignment, and module locking logic

SessionPoolReusable Claude session management with automatic recycling

HierarchyOrg chart management with cycle detection via Kahn's algorithm

SkillMemoryStructured knowledge graph stored in .shazam/memories/

StorePersistence abstraction layer (SQLite primary, JSON fallback)

EventBusPub/sub event system for real-time WebSocket streaming

Execution Flow

Boot — OTP supervision tree starts TaskBoard, SessionPool, and per-company RalphLoops
Task Submission — Tasks are added via CLI or API and stored in ETS-backed TaskBoard
Scheduling — TaskScheduler selects tasks based on agent role, availability, and module locks
Execution — TaskExecutor builds prompts and runs them via Claude Code sessions from the pool
Delegation — PMs may output subtask JSON blocks, automatically parsed and assigned
Completion — Results propagate via EventBus, metrics are recorded, sessions recycled

Environment Variables

SHAZAM_PORT

Override default server port (default: 4040)

Troubleshooting

Agents are idle — tasks not being picked up

Check that RalphLoop is running and agents match the task domain.

# Check system status
mix shazam.status

# Verify the agent roles and domains match your task
# Re-apply config if you changed shazam.yaml
mix shazam.apply

Module lock conflict — task rejected

Another agent is already working on the same code module. Shazam prevents concurrent edits.

# Check which agent holds the lock
mix shazam.status

# Wait for the current task to complete, or disable module locking:
# In shazam.yaml: config.module_lock: false

Rate limit errors from Claude API

Too many concurrent requests to the Claude API.

# Reduce concurrent agents in shazam.yaml:
# config.max_concurrent: 2

SQLite errors on startup

SQLite3 library not found. Shazam will fall back to JSON storage.

# Install SQLite3 (macOS)
brew install sqlite3

# Install SQLite3 (Ubuntu/Debian)
sudo apt-get install libsqlite3-dev

# Or just let Shazam use JSON fallback — it works automatically

Port 4040 already in use

Another process is using the default API port.

# Use a different port
mix shazam.start --port 5050

# Or set via environment variable
export SHAZAM_PORT=5050