Skip to content

raphaelbarbosaqwerty/shazam-cli

BranchesTags

Repository files navigation

Shazam

Autonomous AI agent teams, right from your terminal.

Shazam is an open-source CLI that orchestrates teams of Claude AI agents. You describe what you want built. A PM agent breaks it down, assigns subtasks to developer agents, and they execute — all while you watch in a real-time TUI dashboard.

shazam❯ Build a REST API for user authentication with JWT tokens
  22:15:03 [pm]        Created: Build a REST API for user authentication...
  22:15:08 [pm]        Started: task_1
  22:15:14 [pm]        Completed: task_1
  22:15:14 [senior_1]  Started: Implement JWT middleware and token validation
  22:15:14 [senior_2]  Started: Create user registration and login endpoints
  22:15:14 [qa_1]      Started: Write authentication test suite

Website: shazam.dev | Docs: shazam.dev/docs | License: MIT

Shazam Demo

Ecosystem

Package Description
shazam-core Backend engine — TaskBoard, RalphLoop, Providers, Plugins, API
shazam-cli CLI + TUI interface (this repo)
shazam-dashboard Web dashboard — Vue 3 + Tailwind
shazam-vscode VS Code extension (coming soon)

Why Shazam?

  • Natural language in, working code out. Type what you want. The PM breaks it down. Developers implement. QA tests.
  • Human-in-the-loop. Every subtask needs your approval before agents execute. You stay in control.
  • Real-time TUI. Watch agents work in a beautiful terminal interface with scrollable events, task management, and agent dashboards.
  • Team templates. Spin up a backend team with /team create backend --devs 2 --qa 1 in one command.
  • Session pooling. Agents reuse Claude sessions across tasks — saves tokens and preserves context.
  • Open source. Built with Elixir/OTP for fault-tolerance and a Rust TUI for performance.

How It Works

You (CEO) ──> describe task in natural language
                │
           PM Agent (Haiku) ──> breaks down into subtasks
                │
     ┌──────────┼──────────┐
     │          │          │
 Dev Agent   Dev Agent   QA Agent
 (Opus)      (Sonnet)    (Sonnet)
 implements  implements  writes tests
  1. You type a task in the interactive shell
  2. The PM agent decomposes it into subtasks with dependencies
  3. Subtasks go to your approval queue (or auto-approve)
  4. Developer agents execute in parallel, respecting module locks
  5. QA agents validate the output
  6. You review results in the TUI

Features

Feature Description
Interactive TUI Rust-powered terminal with overlays for tasks, agents, config, dashboard
Ghost text autocomplete Tab-completable /commands with inline hints
Task action menu Select a task, press Enter, approve/reject/pause/kill/retry
Agent management /agent add, /agent edit, /agent remove with YAML persistence
Team templates /team create <domain> --devs N --qa N creates entire teams
10 agent presets PM, Senior Dev, Junior Dev, QA, Designer, Researcher, DevOps, Writer, Market Analyst, Competitor Analyst
Session pooling Reuses Claude sessions (recycles after 8 tasks or 15 min idle)
Module locking Prevents concurrent edits to the same file
Peer reassignment Idle agents pick up tasks from busy peers
Auto-retry Exponential backoff (5s, 15s, 30s) for failed tasks
Human-in-the-loop PM subtasks require approval before execution
Real-time events Live feed of agent activity with scrollbar and mouse support
REST API HTTP endpoints + WebSocket for external integrations
Task search /search filters tasks by title in real-time
Export to markdown /export saves all tasks and results to a .md file
Persistent history Command history saved across sessions
Multi-project Each project directory gets isolated tasks, agents, and metrics
Task detail view Select a task in /tasks to see full result output
Markdown task files Tasks persist as .md files in .shazam/tasks/ — version-controlled, human-readable
PR Reviewer Review PRs with full codebase context, learn from team review patterns
Multi-repo workspaces Agents work across multiple repos simultaneously (backend + frontend + mobile)
File mentions Type @path/to/file in tasks to include file contents as context
Image attachments Paste image paths into tasks — auto-saved to .shazam/attachments/
Token tracking Real-time token usage and cost ($) per agent, persisted across sessions
QA checklists Auto-generated test cases for completed tasks, QA agent validates and marks checkboxes
Execution plans /plan creates phased plans with dependencies, approve to create all tasks at once
Editable agent configs Agent prompts stored as .md files in .shazam/agents/ — fully customizable
Plugin system Extensible middleware — hook into task creation, completion, agent queries with .shazam/plugins/*.ex
Multi-provider Use different AI CLIs per agent — Claude Code, Codex, Cursor, Gemini
Context persistence Agents learn across tasks — TF-IDF retrieval, auto-extracted learnings, atomized topic files
Git-awareness Agents see branch, status, recent commits, and modified files automatically
Agent queries Agents can query each other's knowledge without creating tasks
Project auto-detect shazam init scans your project and suggests agents, domains, and tech stack
Agent sparkline Real-time activity heartbeat (▁▂▃▄▅▆▇█) with stall detection
Task detail view Press Enter on any task to see full result with markdown formatting
Inline task actions a/r/p/x keybindings for approve/reject/pause/kill in task overlay
Enhanced status bar Sparklines, cost, git branch, provider — all in one glance
Circuit breaker Auto-pauses after 3 consecutive failures — prevents runaway token spend
Health check /health shows agents, stalls, circuit breaker, memory, disk
Task deduplication Prevents duplicate tasks from PM creating the same subtask twice
excluded_paths Exclude specific paths from domain restrictions (e.g., block lib/secrets/ even within lib/)
Dashboard advanced metrics Avg task duration, tasks/hour, tokens/task, retry rate via Metrics.get_dashboard_stats/0
QA real test generation QA agents write and run actual tests, not just checklists (QAManager.generate_test_task/1)
Secrets obfuscation plugin Detects and masks API keys, tokens, passwords before sending to AI providers
JSON logger plugin Structured event logs in .shazam/logs/events.json (secrets auto-scrubbed)
Plugin install from GitHub /plugins install <owner>/<repo> to install plugins directly from GitHub repos

Architecture

                          +---------------+
                          |   YOU (CEO)   |
                          |  Human-in-    |
                          |  the-Loop     |
                          +-------+-------+
                                  |
                           Creates tasks &
                           approves outputs
                                  |
                 +----------------+----------------+
                 |                |                |
          +------v------+  +-----v------+  +------v------+
          | PM Dev Team  |  | PM Analysts |  |  PM Design  |
          | (Haiku 4.5)  |  | (Haiku 4.5) |  | (Haiku 4.5) |
          +------+-------+  +-----+------+  +-------------+
                 |                 |
      +------+--+--+        +-----+-----+
      |      |     |        |           |
   +--v--++--v-++--v--+  +--v----+  +---v----+
   | Dev  || Dev|| QA  |  |Market |  |Compet. |
   | Sr.  || Jr.||     |  |Analyst|  |Analyst |
   +------++----++-----+  +------+   +--------+
   Opus/   Sonnet Sonnet   Sonnet     Sonnet
   Sonnet

OTP Supervision Tree

Shazam.Supervisor (one_for_one)
  |- Registry (CompanyRegistry)
  |- Registry (RalphLoopRegistry)
  |- DynamicSupervisor (AgentSupervisor)
  |- DynamicSupervisor (CompanySupervisor)
  |- DynamicSupervisor (RalphLoopSupervisor)
  |- Shazam.TaskBoard (GenServer, ETS-backed)
  |- Shazam.SessionPool (GenServer)
  |- Shazam.API.EventBus (GenServer)
  |- Shazam.Metrics (GenServer)
  |- Shazam.AgentInbox (GenServer)
  |- Shazam.PluginManager (GenServer)
  +- Bandit HTTP Server (port 4040)

Task Execution Flow

RalphLoop polls TaskBoard every 5s
  -> TaskScheduler selects best pending task + agent
    -> TaskExecutor builds prompt (memory, skills, role rules)
      -> PluginManager.before_query() — plugins can mutate prompt
        -> SessionPool.checkout() gets reused Claude session
          -> Orchestrator.execute_on_session() runs on Claude
        -> PluginManager.after_query() — plugins can mutate result
          -> SubtaskParser extracts subtasks from output
            -> PluginManager.after_task_complete() — plugins notified
              -> TaskBoard.complete() marks original task done

Role Separation

Role Can Do Cannot Do
PM Delegate, break down tasks, coordinate Read code, use dev tools
Dev Implement features, fix bugs, refactor Write tests
QA Write tests, report bugs, validate Implement features
Analyst Research, analyze data, report Write code

Installation

Quick Install (one command)

curl -fsSL https://raw.githubusercontent.com/raphaelbarbosaqwerty/shazam-cli/main/setup.sh | bash

The setup script automatically detects your environment:

  • If Nix is installed → uses Nix for all dependencies (easiest, recommended)
  • If Nix is not installed → checks for Elixir, Rust, and Claude Code manually

Recommended: Install with Nix (zero dependency hassle)

If you don't have Elixir or Rust installed, Nix is the fastest path. It provides everything automatically:

# 1. Install Nix (one-time, takes ~2 minutes)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh

# 2. Install Shazam (Nix handles Elixir, Rust, SQLite for you)
curl -fsSL https://raw.githubusercontent.com/raphaelbarbosaqwerty/shazam-cli/main/setup.sh | bash

Without Nix (manual prerequisites)

If you prefer not to use Nix, install these first:

  • Elixir >= 1.18 and Erlang/OTP >= 27 (install)
  • Rust (install)
  • Claude Code installed and logged in (install)

Then run the same setup command:

curl -fsSL https://raw.githubusercontent.com/raphaelbarbosaqwerty/shazam-cli/main/setup.sh | bash

macOS note: Apple ships /usr/bin/shazam (ShazamKit). If there's a conflict, use shz instead — it's installed automatically as an alias:

shz init
shz shell

Updating

shazam update

This fetches the latest git tag (e.g., v0.6.0), checks it out, rebuilds, and installs automatically. Updates always target stable tagged releases, not the HEAD of main.

Quick Start

1. Initialize a Project

shazam init

This creates a shazam.yaml in the current directory with a starter company configuration.

2. Configure Your Team

Edit shazam.yaml (see Configuration below).

3. Start the Interactive Shell

shazam

This automatically opens the interactive TUI (no need to type shazam shell). Inside:

shazam❯ /start                    # Boot agents and RalphLoop
shazam❯ /tasks                    # View task board
shazam❯ Build user authentication # Creates task for PM (natural language)
shazam❯ /aa                       # Approve all pending subtasks
shazam❯ /dashboard                # Live agent status
shazam❯ /agents                   # View agents by domain

Alternative: CLI Commands

# Start server mode (HTTP API on port 4040)
shazam start

# Create a task
shazam task "Implement JWT auth" --to pm

# Monitor
shazam logs
shazam dashboard
shazam org

Programmatic Usage (Elixir)

# Direct parallel execution
agents = [
  %{name: "researcher", role: "analyst", prompt: "Research auth best practices"},
  %{name: "implementer", role: "developer", prompt: "Implement JWT auth"}
]
results = Shazam.run(agents)

# Start a full company
Shazam.start_company(%{
  name: "AuthTeam",
  mission: "Build authentication system",
  agents: [
    %{name: "pm", role: "Project Manager", supervisor: nil},
    %{name: "dev", role: "Senior Developer", supervisor: "pm"},
    %{name: "qa", role: "QA Engineer", supervisor: "pm"}
  ]
})

# Assign task
Shazam.assign("AuthTeam", "pm", "Implement JWT authentication")

Configuration

Shazam is configured via shazam.yaml (or .shazam/shazam.yaml).

Full Configuration Reference

# Default AI CLI provider for all agents
provider: claude_code  # claude_code | codex | cursor | gemini

# Company definition
company:
  name: "MyTeam"
  mission: "Build and maintain the core product"
  workspace: "/path/to/project"  # Optional, defaults to CWD

# Domain access restrictions (optional)
domains:
  backend:
    description: "Backend services and API"
    paths:
      - "lib/"
      - "src/"
  frontend:
    description: "Frontend application"
    paths:
      - "app/"
      - "components/"

# Agent definitions
agents:
  pm:
    role: "Project Manager"
    # supervisor: null (top of hierarchy)
    budget: 200000                          # Token budget
    model: "claude-haiku-4-5-20251001"      # AI model
    tools:                                  # Allowed tools
      - "Read"
      - "Grep"
      - "WebSearch"
    system_prompt: "You are a PM..."        # Custom prompt (optional)
    domain: "backend"                       # Restrict to domain paths
    provider: "claude_code"                 # AI CLI provider (overrides global)
    heartbeat_interval: 60000               # Health check interval (ms)

  senior_dev:
    role: "Senior Developer"
    supervisor: "pm"                        # Reports to PM
    budget: 150000
    tools:
      - "Read"
      - "Edit"
      - "Write"
      - "Bash"
      - "Grep"
      - "Glob"
    domain: "backend"

  qa:
    role: "QA Engineer"
    supervisor: "pm"
    budget: 100000

# RalphLoop configuration
config:
  auto_approve: false       # true = subtasks execute immediately
                            # false = subtasks go to approval queue
  auto_retry: true          # Retry failed tasks automatically
  max_concurrent: 4         # Max parallel agent executions
  max_retries: 2            # Retry attempts before giving up
  poll_interval: 5000       # Task polling interval (ms)
  module_lock: true         # Prevent concurrent edits to same file
  peer_reassign: true       # Assign to idle peers if agent is busy

# Plugins (optional) — middleware hooks for the agent lifecycle
plugins:
  - name: slack_notifier    # Matches module name (ShazamPlugin.SlackNotifier)
    enabled: true
    config:
      webhook_url: "https://hooks.slack.com/services/..."
  - name: auto_context
    enabled: true

Default Tool Sets by Role

Role Default Tools
Manager/PM Read, Grep, Glob, WebSearch
Developer Read, Edit, Write, Bash, Grep, Glob
QA Read, Edit, Write, Bash, Grep, Glob
Analyst Read, Grep, WebSearch, WebFetch

Default Values

Setting Default
Budget 100,000 tokens
Heartbeat interval 60,000 ms
Poll interval 5,000 ms
Max concurrent 4
Max retries 2
HTTP port 4040

CLI Reference

USAGE: shazam <command> [options]
Command Description Key Flags
init Create a new shazam.yaml configuration —
start Boot server from YAML config -p/--port, -f/--file, --no-resume
shell Interactive REPL terminal -p/--port, -f/--file
status Show running companies and agents -c/--company, -p/--port
stop Stop a company -c/--company, -p/--port, --all
task "title" Create a task --to agent, -c/--company, -p/--port
org Display org chart -c/--company, -p/--port
logs [agent] Stream live events -c/--company, -p/--port
agent add <name> Add agent to running company --role, --supervisor, --domain, --budget, --model
apply Apply YAML config changes to running system -f/--file, -p/--port
dashboard Interactive TUI dashboard -c/--company, -p/--port
version Show version —
update Auto-update to latest tagged release (fetch tags + checkout + rebuild) —
help Show help —

Examples

# Start with custom port and config file
shazam start -p 5000 -f my-team.yaml

# Create a task assigned to a specific agent
shazam task "Fix the login bug" --to senior_dev -c MyTeam

# Stop all companies
shazam stop --all

# Add an agent dynamically
shazam agent add designer --role "UI Designer" --supervisor pm --budget 80000

# Apply updated YAML without restarting
shazam apply -f shazam.yaml

Interactive Shell Commands

When running shazam (or shazam shell), the following /commands are available:

Command Description
/start Start agents
/stop Stop agents (keep REPL open)
/resume Resume RalphLoop
/status Refresh status bar
/dashboard Open agent dashboard with metrics and current tasks
/agents List all agents with status
/org Show org chart
/tasks List tasks (--clear, --sync, --export)
/task <title> Create a new task (--to agent)
/approve <id> Approve a specific task by ID
/aa Approve all pending tasks (alias: /approve-all)
/reject <id> Reject a pending task
/msg <agent> <msg> Send message to agent
/auto-approve Toggle auto-approve (on/off)
/config Show current configuration
/agent add <name> Add new agent (--role, --domain, --supervisor, --budget)
/agent edit <name> Edit agent (--role, --domain, --budget, --model)
/agent remove <name> Remove agent
/pause-task <id> Pause a task
/resume-task <id> Resume a paused task
/kill-task <id> Kill running task
/retry-task <id> Retry failed task
/delete-task <id> Delete a task
/search <query> Search tasks by title
/export [file] Export tasks to markdown file
/clear Clear scroll region
/help Show help
/review <pr> Review a pull request (number or URL)
/review --learn Learn patterns from merged PR reviews
/review --post <task_id> Post completed review to GitHub with inline comments
/review --check <pr> Verify if previous review comments were addressed
/review --resolve <pr> Resolve all conversation threads on a PR
/workspaces List configured workspaces (multi-repo)
/plugins List loaded plugins
/plugins reload Hot-reload plugins from .shazam/plugins/
/plugins install <owner>/<repo> Install plugin from GitHub repo
/plugins install <owner>/<repo> --path file.ex Install specific plugin file from repo
/plugins remove <name> Remove a plugin
/restart Restart Shazam (stop agents + re-init)
/github sync Re-import tasks from GitHub Projects
/review --learn Learn patterns from merged PR reviews
/review --patterns Show learned review patterns
/quit Exit Shazam

Keyboard shortcuts: ↑/↓ command history, Tab accept ghost text, PgUp/PgDn or mouse scroll events, Enter task detail view in /tasks, a approve, r reject, p pause, x kill (in task overlay), Ctrl+C exit, ESC close overlay. Command history is saved across sessions (~/.shazam/tui_history).

API Reference

Shazam exposes a REST API on port 4040 (configurable).

Endpoints

Method Path Description
GET /api/companies List all running companies
POST /api/companies Create a new company
GET /api/companies/:name/agents List agents in a company
PUT /api/companies/:name/agents Update agents configuration
GET /api/companies/:name/org-chart Get organizational chart
POST /api/companies/:name/tasks Create a task in a company
GET /api/tasks List tasks (supports filters)
GET /api/events/recent Get recent events

WebSocket

Connect to ws://localhost:4040/ws for real-time event streaming. Events include:

  • Agent text output (deltas and complete)
  • Tool usage notifications
  • Task status changes
  • System events

Core Concepts

Companies

A company is a self-contained unit with its own hierarchy of agents, task board, and execution loop. Multiple companies can run simultaneously, each managing independent workstreams.

RalphLoop

The RalphLoop is the heart of each company. It continuously polls the TaskBoard for pending tasks, selects the best agent for each task, executes it, and processes the output (including subtask creation). Configuration options:

  • auto_approve — Skip approval queue for PM-created subtasks
  • max_concurrent — Limit parallel executions
  • poll_interval — How often to check for new tasks
  • module_lock — Prevent concurrent edits to the same file
  • peer_reassign — Redistribute work to idle agents

Session Pool

The SessionPool maintains reusable Claude Code sessions per agent. This preserves context across tasks and significantly reduces token usage. Sessions are automatically recycled after 8 tasks or 15 minutes of inactivity.

Task Lifecycle

pending -> in_progress -> completed
                       -> failed (-> retry -> pending)
                       -> awaiting_approval -> approved -> pending
                                            -> rejected

Tasks support: creation, atomic checkout, completion, failure, retry, pause/resume, reassignment, soft delete, and hard purge.

Task Files

Tasks are automatically persisted as markdown files in .shazam/tasks/ relative to your project workspace. Each task is a .md file with YAML frontmatter:

.shazam/tasks/
├── task_1.md    # completed
├── task_2.md    # in_progress
└── task_3.md    # pending

You can:

  • Create tasks in bulk by adding .md files to the folder manually
  • Import with /tasks --sync to load files into the task board
  • Export with /tasks --export to save all current tasks as files
  • Version control task files alongside your code

Task file format:

---
id: task_1
title: "Implement user authentication"
status: completed
assigned_to: senior_1
created_by: human
company: MyProject
created_at: 2026-03-18T10:00:00Z
completed_at: 2026-03-18T10:30:00Z
---

## Description

Implement JWT-based authentication.

## Result

Implemented in lib/auth/ — 3 files created.

Agent Config Files

Agent system prompts and settings are stored as editable markdown files in .shazam/agents/:

.shazam/agents/
├── pm.md
├── senior_1.md
├── senior_2.md
└── reviewer.md

Each file has YAML frontmatter + a markdown body as the system prompt:

---
role: Senior Developer
model: claude-opus-4-6
budget: 150000
tools: [Read, Edit, Write, Bash, Grep, Glob]
---

You are a Senior Developer. You write clean, production-ready code.

## Responsibilities
- Implement features and fix bugs
- Follow existing project conventions

## Restrictions
- You do NOT write tests — QA handles testing
- Stay within your domain paths
  • shazam init creates .md files from presets automatically
  • /agents --init generates .md files for existing projects
  • Edit any .md to customize the agent's behavior, restrictions, or focus
  • Changes take effect on the next task (no restart needed)
  • If no .md exists, the hardcoded preset is used as fallback
  • Multiple agents can share the same .md via the config: field in YAML:
agents:
  senior_1:
    role: Senior Developer
    supervisor: pm
    config: .shazam/agents/backend_dev.md   # custom config file

  senior_2:
    role: Senior Developer
    supervisor: pm
    config: .shazam/agents/backend_dev.md   # reuses same config!

Loading priority: config: field → .shazam/agents/<name>.md → hardcoded preset

Plugins

Shazam has an extensible plugin system that lets you hook into the agent lifecycle. Plugins are Elixir modules placed in .shazam/plugins/*.ex, compiled at runtime when you run /start.

Lifecycle Events

Event When Can Mutate
on_init /start boots agents —
before_task_create Before task is created Task attributes (or halt)
after_task_create After task is created — (observe)
before_task_complete Before task is marked complete Result output (or halt)
after_task_complete After task is marked complete Result output
before_query Before prompt is sent to agent Prompt text (or halt)
after_query After agent responds Agent response
on_tool_use When agent uses a tool — (observe only)

Writing a Plugin

Create a file in .shazam/plugins/ (alphabetical order = execution order):

# .shazam/plugins/01_slack_notify.ex
defmodule ShazamPlugin.SlackNotify do
  use Shazam.Plugin

  @impl true
  def after_task_complete(task_id, result, ctx) do
    url = ctx.plugin_config["webhook_url"]
    if url do
      payload = Jason.encode!(%{text: "Task #{task_id} done in #{ctx.company_name}"})
      spawn(fn -> System.cmd("curl", ["-s", "-X", "POST", "-d", payload, url]) end)
    end
    {:ok, result}
  end
end

Plugin Context

Every callback receives a context map with:

%{
  company_name: "MyProject",
  agents: [%AgentWorker{name: "pm", role: "Project Manager", ...}, ...],
  tasks: [%{id: "task_1", title: "...", status: :pending, ...}, ...],
  plugin_config: %{"webhook_url" => "..."}  # from shazam.yaml
}

Plugin Configuration

# shazam.yaml
plugins:
  - name: slack_notify       # matches ShazamPlugin.SlackNotify (underscored)
    enabled: true
    events:                  # only trigger on these events (omit for all)
      - after_task_complete
      - after_task_create
    config:
      webhook_url: "https://hooks.slack.com/..."
  - name: auto_context
    enabled: false            # disabled without deleting the file

Event Filtering

By default, plugins run on all events they implement. Use the events: field to restrict when a plugin is called:

plugins:
  - name: logger
    events: [after_task_create, after_task_complete]  # only these two
  - name: auto_context
    events: [before_query]                            # only prompt injection
  - name: webhook
    # no events: field = runs on all implemented callbacks

Available events:

Event Phase Can Mutate Description
on_init startup — Called when /start boots agents
before_task_create before attrs or halt Before a task is created
after_task_create after task After a task is created
before_task_complete before result or halt Before marking task complete
after_task_complete after result After task is marked complete
before_query before prompt or halt Before prompt is sent to agent
after_query after response After agent responds
on_tool_use notify — (observe only) When an agent uses a tool

Commands

  • /plugins — list loaded plugins
  • /plugins reload — hot-reload plugins from disk (no restart needed)
  • /plugins install <owner>/<repo> — install plugins from a GitHub repo
  • /plugins remove <name> — remove an installed plugin

Installing Plugins

# Install all plugins from a GitHub repo
/plugins install ShazamAI/shazam-core

# Install a specific plugin file
/plugins install ShazamAI/shazam-core --path examples/plugins/06_json_logger.ex

# Remove a plugin
/plugins remove json_logger

# List loaded plugins
/plugins

# Reload after manual changes
/plugins reload

Available Example Plugins

Plugin File Description
GitHub Projects 05_github_projects.ex Sync tasks with GitHub org-level Projects board
JSON Logger 06_json_logger.ex Structured event logs in .shazam/logs/events.json (secrets auto-scrubbed)
Secrets Obfuscation 07_secrets_obfuscation.ex Masks API keys, tokens, passwords before sending to AI providers
Webhook 02_webhook.ex POST notifications to Slack/HTTP endpoints
Auto-context 03_auto_context.ex Inject project context into agent prompts

Context Persistence

Agents automatically accumulate context as they complete tasks — they learn from their own output. This works with all providers (Claude, Codex, Cursor, Gemini).

How it works

  1. Agent completes a task
  2. ContextManager extracts a summary + routes it to a topic file
  3. Learnings are auto-extracted (decisions, discoveries, tech stack, warnings)
  4. Next task: agent receives its history + team activity + TF-IDF relevant context

Storage

.shazam/context/
  agents/
    senior_1/
      index.md              # auto-generated links + key learnings
      _learnings.md         # "Project uses Supabase", "JWT uses jose library"
      implement_jwt_auth.md # everything about auth
      build_rest_api.md     # endpoints created
  team_activity.md          # chronological log of all agents

What agents receive in their prompt

## What You Know
- Project uses Vue.js
- Project uses Supabase
- API uses JWT with 1h expiration via jose library

## Your Recent Work
### [2026-03-20 12:00] Fix JWT expiration
  Changed token TTL...

## Recent Team Activity
### [2026-03-20 11:55] pm: Plan auth system
  Delegated 3 subtasks...

## Related Context
### [2026-03-20 11:30] senior_2: Setup database
  Created users table...

Configuration

config:
  context_history: 5      # last N tasks per agent
  team_activity: 10       # last N team tasks
  context_budget: 4000    # max chars injected into prompt

Engineering Manager (Multi-team)

For projects with multiple teams/repositories, add an Engineering Manager above the PMs. The Manager receives all tasks and delegates to the correct PM based on context.

CEO (you) → Engineering Manager
  ├── PM Dashboard → dashboard_dev_1, dashboard_dev_2, dashboard_dev_3
  └── PM VS Code   → vscode_dev_1, vscode_dev_2, vscode_dev_3

agents:
  manager:
    role: Engineering Manager
    model: claude-haiku-4-5-20251001
    tools: [Read, Grep, Glob, WebSearch]

  pm_dashboard:
    role: Project Manager — Dashboard
    supervisor: manager
    domain: dashboard
    workspace: dashboard

  pm_vscode:
    role: Project Manager — VS Code Extension
    supervisor: manager
    domain: vscode-extension
    workspace: vscode

  dashboard_dev_1:
    role: Senior Frontend Developer
    supervisor: pm_dashboard
    workspace: dashboard
    # ...

The Manager is only needed with multiple teams. Single-team projects use PM directly at the top.

Subtask Delegation

When a PM agent outputs a JSON block with subtasks, the SubtaskParser automatically creates child tasks:

[
  {"title": "Implement auth middleware", "assigned_to": "senior_dev", "depends_on": null},
  {"title": "Write auth tests", "assigned_to": "qa", "depends_on": "Implement auth middleware"}
]

Human-in-the-Loop

When auto_approve: false, PM-generated subtasks enter an awaiting_approval state. The user must approve or reject each subtask before it executes. This provides oversight over the AI delegation chain.

Module Locking

The ModuleManager prevents multiple agents from editing the same file simultaneously. When an agent checks out a task that touches specific modules, those modules are locked until the task completes.

Codex Fallback

If Claude hits rate limits, Shazam can fall back to GPT-5-Codex via the Codex CLI. Configure via environment variables:

export CODEX_FALLBACK_MODEL="gpt-5-codex"
export CODEX_CLI_BIN="codex"

Module Reference

Core Modules (lib/shazam/)

Module File Description
Shazam lib/shazam.ex Public API — run/2, pipeline/2, start_company/1, assign/3
Shazam.Application application.ex OTP supervision tree bootstrap
Shazam.Company company.ex GenServer managing agent hierarchy, tasks, org chart
Shazam.Orchestrator orchestrator.ex Parallel/pipeline agent execution via Claude Code
Shazam.RalphLoop ralph_loop.ex Per-company task polling and execution loop

Task System

Module File Description
Shazam.TaskBoard task_board.ex ETS-backed task CRUD with atomic checkout
Shazam.TaskScheduler task_scheduler.ex Task selection, peer reassignment, module locking
Shazam.TaskExecutor task_executor.ex Prompt building, session management, execution
Shazam.SubtaskParser subtask_parser.ex Extract subtasks from agent output
Shazam.TaskTemplates task_templates.ex Pre-built prompt templates
Shazam.RetryPolicy retry_policy.ex Exponential backoff for failed tasks

Agent & Organization

Module File Description
Shazam.AgentWorker agent_worker.ex Agent configuration struct
Shazam.AgentPresets agent_presets.ex Pre-configured role templates
Shazam.AgentInbox agent_inbox.ex Per-agent message queue
Shazam.Hierarchy hierarchy.ex Org chart, cycle detection (Kahn's algorithm)
Shazam.ModuleManager module_manager.ex File-level access control per domain

Session & Persistence

Module File Description
Shazam.SessionPool session_pool.ex Reusable Claude Code session management
Shazam.Store store.ex Persistence abstraction (SQLite or JSON fallback)
Shazam.Repo repo.ex SQLite interface (WAL mode, KV store)

Memory

Module File Description
Shazam.MemoryBank memory_bank.ex Per-agent markdown memory files
Shazam.SkillMemory skill_memory.ex Structured skill-graph knowledge system

API & CLI

Module File Description
Shazam.API.Router api/router.ex REST API endpoint handlers
Shazam.API.EventBus api/event_bus.ex Real-time event pub/sub broadcasting
Shazam.API.WebSocket api/websocket.ex WebSocket connection handler
Shazam.CLI cli.ex Command-line interface entry point
Shazam.CLI.REPL cli/repl.ex Interactive shell with command history
Shazam.CLI.YamlParser cli/yaml_parser.ex shazam.yaml parsing and validation
Shazam.CLI.Formatter cli/formatter.ex Terminal output formatting (colors, tables)

Context & Intelligence

Module File Description
Shazam.ContextManager context_manager.ex Cross-provider context persistence with atomized topic files
Shazam.ContextRAG context_rag.ex TF-IDF retrieval engine — pure Elixir, zero dependencies
Shazam.GitContext git_context.ex Git-awareness — branch, status, commits injected into prompts
Shazam.AgentQuery agent_query.ex Agent-to-agent knowledge sharing (passive context lookup)
Shazam.AgentPulse agent_pulse.ex Real-time activity sparkline with stall detection
Shazam.CircuitBreaker circuit_breaker.ex Auto-pause after consecutive failures
Shazam.ProjectDetector project_detector.ex Auto-detect tech stack, frameworks, domains from project files

Provider System

Module File Description
Shazam.Provider provider.ex Behaviour for AI CLI providers (6 callbacks)
Shazam.Provider.ClaudeCode provider/claude_code.ex Claude Code provider with session support
Shazam.Provider.Codex provider/codex.ex OpenAI Codex CLI provider (stateless)
Shazam.Provider.Cursor provider/cursor.ex Cursor CLI provider (stateless)
Shazam.Provider.Gemini provider/gemini.ex Google Gemini CLI provider (stateless)
Shazam.Provider.Resolver provider/resolver.ex Maps provider names to modules

Plugin System

Module File Description
Shazam.Plugin plugin.ex Behaviour with 8 optional lifecycle callbacks
Shazam.PluginManager plugin_manager.ex GenServer — loads plugins, runs event pipelines
Shazam.PluginLoader plugin_loader.ex Runtime compilation of .shazam/plugins/*.ex

Infrastructure

Module File Description
Shazam.Metrics metrics.ex Token usage and performance tracking
Shazam.FileLogger file_logger.ex File-based logging

Memory Systems

Shazam has two complementary memory systems:

MemoryBank (Legacy)

Per-agent markdown files at .shazam/memory/{agent_name}.md. Each file is capped at ~8,000 characters and contains:

  • Project Overview
  • Architecture & Patterns
  • Agent Responsibilities
  • Lessons Learned
  • Dependencies

SkillMemory (Current)

A structured skill-graph system at .shazam/memories/ with YAML frontmatter:

.shazam/memories/
  |- SKILL.md              # Root skill index
  |- project/              # Project-wide knowledge
  |    |- overview.md
  |    |- architecture.md
  |    +- conventions.md
  |- agents/               # Per-agent context
  |    |- pm.md
  |    +- senior_dev.md
  |- rules/                # Domain rules
  |    |- testing.md
  |    +- git-workflow.md
  +- decisions/            # Architectural Decision Records
       +- 001-auth-strategy.md

Each skill file uses frontmatter:

---
name: skill-name
description: One line description
tags: tag1, tag2
---
Content here. Reference other skills: [./rules/testing.md](./rules/testing.md)

Persistence

Shazam automatically selects the best available storage backend:

Backend Condition Storage Location
SQLite (primary) Exqlite available .shazam/shazam.db
JSON (fallback) SQLite unavailable ~/.shazam/{key}.json

Persisted Data

  • Workspace path — Current working directory
  • Company configs — Agents, hierarchy, mission, domain config (company:{name})
  • Tasks — Full task board per company (tasks:{company})

All data is restored on startup. Companies and their RalphLoops resume automatically.

Contributing

Development Setup

The recommended way to set up a development environment is with Nix:

# Clone and enter
git clone https://github.com/raphaelbarbosaqwerty/shazam-cli.git
cd shazam-cli

# Option A: Use Nix (recommended — provides all dependencies automatically)
nix develop

# Option B: Manual setup (install Elixir, Erlang, and Rust yourself)
# See Prerequisites section above

# Install deps
mix deps.get

# Run tests
mix test

# Start in development
iex -S mix

Project Structure

lib/
  shazam.ex              # Public API
  shazam/
    api/                 # HTTP API, WebSocket, EventBus
    cli/                 # CLI, REPL, YAML parser, formatter
      tui_port/
        commands/        # System, Tasks, Agents, Review, Tools
    company/
      builder.ex         # Agent config building & persistence
    task_board/
      persistence.ex     # ETS ↔ disk serialization
    application.ex       # OTP supervision tree
    company.ex           # Company GenServer
    orchestrator.ex      # Agent execution engine
    ralph_loop.ex        # Task execution loop
    task_board.ex        # Task management (ETS)
    task_executor.ex     # Prompt building & execution
    plugin.ex            # Plugin behaviour (8 lifecycle hooks)
    plugin_manager.ex    # Plugin loading & pipeline execution
    plugin_loader.ex     # Runtime .ex compilation
    session_pool.ex      # Session reuse
    ...
config/
  config.exs             # Application configuration
test/
  ...

Code Style

  • Follow standard Elixir conventions
  • Format code with mix format
  • Use module docs (@moduledoc) for all public modules
  • Use typespecs for public functions

Environment Variables

Variable Default Description
CODEX_FALLBACK_MODEL gpt-5-codex Fallback model when Claude is rate-limited
CODEX_CLI_BIN codex Path to Codex CLI binary

Agent Presets

Shazam includes pre-configured agent templates for common roles:

Preset Role Default Model Use Case
pm Project Manager Haiku 4.5 Task delegation and coordination
senior_dev Senior Developer Opus/Sonnet Complex implementation and architecture
junior_dev Junior Developer Sonnet Straightforward implementation
qa QA Engineer Sonnet Testing and bug reporting
researcher Researcher Sonnet Information gathering and analysis
designer UI Designer Sonnet Interface design and prototyping
devops DevOps Engineer Sonnet Infrastructure and deployment
writer Technical Writer Sonnet Documentation
market_analyst Market Analyst Sonnet Market research
competitor_analyst Competitor Analyst Sonnet Competitive analysis
pr_reviewer PR Reviewer Opus 4.6 Code review with codebase context

Team Templates

Quickly create entire teams with one command:

# Create a backend team: 2 devs + 1 QA
/team create backend --devs 2 --qa 1

# Create a frontend team: 3 devs + designer
/team create frontend --devs 3 --designer

# Create a research team: 2 devs + researcher
/team create api --devs 2 --researcher

Multi-Repo Workspaces

Work across multiple repositories simultaneously. Each agent runs in its own workspace:

workspaces:
  backend:
    path: /home/user/projects/backend-api
    domains: ["lib/", "src/"]
  frontend:
    path: /home/user/projects/frontend-web
    domains: ["src/", "components/"]
  mobile:
    path: /home/user/projects/mobile-app
    domains: ["lib/", "src/"]

agents:
  pm:
    role: Project Manager
    budget: 200000

  backend_dev:
    role: Senior Developer
    supervisor: pm
    workspace: backend

  frontend_dev:
    role: Senior Developer
    supervisor: pm
    workspace: frontend

  mobile_dev:
    role: Senior Developer
    supervisor: pm
    workspace: mobile

When you say "Add pagination to the users API and update frontend table and mobile list", the PM assigns subtasks to each agent in their respective repo.

/workspaces    — List configured workspaces and check paths

Web Dashboard

Shazam includes a companion web dashboard built with Vue 3 + Tailwind CSS that connects to the CLI's REST API and WebSocket.

Repository: github.com/ShazamAI/shazam-dashboard

Features:

  • Real-time event feed via WebSocket
  • Task management (create, approve, reject, pause, kill, retry)
  • Agent monitoring with status and metrics
  • Org chart visualization
  • Configuration viewer
  • Dashboard with token usage and cost tracking

The dashboard connects to localhost:4040 (the Shazam API port) and works alongside the TUI — both can run simultaneously.

# Start Shazam CLI (starts the API server)
shazam

# In another terminal, start the dashboard
cd shazam-dashboard
npm install
npm run dev
# Open http://localhost:3000

Tech Stack

Component Technology
Runtime Elixir/OTP (GenServer, ETS, DynamicSupervisor)
AI Engine Claude Code SDK (claude_code ~> 0.29)
HTTP Server Bandit (> 1.0) + Plug (> 1.16)
WebSocket websock_adapter (~> 0.5)
Database SQLite via Exqlite (~> 0.27)
Config Parsing YamlElixir (~> 2.9)
JSON Jason (~> 1.4)
CORS CorsPlug (~> 3.0)
TUI Rust (ratatui + crossterm)

License

See LICENSE for details.

About

Autonomous AI Agent Teams

Resources

Readme

License

MIT license
Activity

Stars

11 stars

Watchers

1 watching

Forks

5 forks
Report repository

Releases

39 tags

Packages

 
 
 

Contributors

Languages