Documentation

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

The script clones the repo, detects dependencies, builds, and installs to ~/bin/.

shazam update

Fetches the latest git tag (e.g., v0.6.0), checks it out, rebuilds, and installs. Always targets stable tagged releases, not HEAD.

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

agents:
  pm:
    role: Project Manager

  backend_dev:
    role: Senior Developer
    supervisor: pm
    workspace: backend       # runs in backend repo

  frontend_dev:
    role: Senior Developer
    supervisor: pm
    workspace: frontend      # runs in frontend repo

  mobile_dev:
    role: Senior Developer
    supervisor: pm
    workspace: mobile        # runs in mobile repo

CEO (you) → Engineering Manager
  ├── PM Dashboard → 3 frontend devs (workspace: dashboard)
  └── PM VS Code   → 3 extension devs (workspace: vscode)

# shazam.yaml
agents:
  manager:
    role: Engineering Manager
    model: claude-haiku-4-5-20251001

  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:
    supervisor: pm_dashboard
    workspace: dashboard
    # ...

1. Create — /plan Build a user auth system with JWT
2. Review — PM generates phases (e.g., Phase 1: DB schema, Phase 2: API endpoints, Phase 3: Tests)
3. Auto-save — Plan is saved to .shazam/plans/ as markdown
4. Approve — /plan --approve plan_1 creates all tasks with depends_on set
5. Execute — RalphLoop respects dependencies, executing phases in order

mkdir -p .shazam/plugins

# Create a plugin file
cat > .shazam/plugins/01_logger.ex << 'EOF'
defmodule ShazamPlugin.Logger do
  use Shazam.Plugin

  @impl true
  def after_task_complete(task_id, result, _ctx) do
    File.write(".shazam/events.log",
      "[#{DateTime.utc_now()}] Task #{task_id} done\n", [:append])
    {:ok, result}
  end
end
EOF

# Start shazam — plugins load automatically on /start
shazam

# .shazam/plugins/02_webhook.ex
defmodule ShazamPlugin.Webhook 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} completed in #{ctx.company_name}"
      })
      spawn(fn ->
        System.cmd("curl", ["-s", "-X", "POST", "-d", payload, url])
      end)
    end
    {:ok, result}
  end
end

# .shazam/plugins/03_auto_context.ex
defmodule ShazamPlugin.AutoContext do
  use Shazam.Plugin

  @impl true
  def before_query(prompt, _agent_name, _ctx) do
    case File.read(".shazam/project_context.md") do
      {:ok, context} -> {:ok, "## Context\n#{context}\n\n#{prompt}"}
      _ -> {:ok, prompt}
    end
  end
end

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

plugins:
  - name: webhook              # matches ShazamPlugin.Webhook
    enabled: true
    events:                    # only these events (omit for all)
      - after_task_complete
      - after_task_create
    config:
      webhook_url: "https://hooks.slack.com/services/..."

  - name: auto_context
    events: [before_query]     # only prompt injection

  - name: logger
    # no events: = runs on all implemented callbacks
    enabled: true

1. Task completes — ContextManager extracts summary and routes to a topic file
2. Learnings extracted — regex patterns detect decisions, tech stack, warnings from output
3. Deduplication — new learnings compared with existing via Jaccard similarity (>0.7 = skip)
4. Next task — agent receives: learnings + history + team activity + TF-IDF relevant context

.shazam/context/
  agents/
    senior_1/
      index.md              # auto-generated links + key learnings
      _learnings.md         # "Project uses Supabase", "JWT uses jose"
      implement_jwt_auth.md # topic: auth work
      build_rest_api.md     # topic: API endpoints
    pm/
      index.md
      _learnings.md
      plan_auth_system.md
  team_activity.md          # chronological log (auto-trimmed)

## What You Know
- Project uses Vue.js
- Project uses Supabase
- API uses JWT with 1h expiration via jose library
- careful: /api/users has no rate limiting

## Your Recent Work
### [2026-03-20] Fix JWT expiration — changed TTL to 24h

## Recent Team Activity
### [2026-03-20] pm: Plan auth system — delegated 3 subtasks

## Related Context (TF-IDF)
### [2026-03-20] senior_2: Setup database — created users table

# shazam.yaml

provider: claude_code          # default for all agents

agents:
  pm:
    role: Project Manager
    provider: claude_code      # explicit — uses Claude

  senior_1:
    role: Senior Developer
    supervisor: pm
    provider: codex            # uses Codex CLI

  senior_2:
    role: Senior Developer
    supervisor: pm
    provider: cursor           # uses Cursor CLI

  senior_3:
    role: Senior Developer
    supervisor: pm
    # no provider: field = inherits global default (claude_code)

1. Resolution — TaskExecutor resolves the provider from agent config (or global default)
2. Session check — Session-based providers (Claude) use SessionPool for reuse; stateless providers skip it
3. Execution — Provider receives the prompt and returns {:ok, text, files}
4. Normalization — All providers return the same result format, so RalphLoop handles output identically

# Start Shazam CLI (starts the API server on :4040)
shazam

# In another terminal
git clone https://github.com/ShazamAI/shazam-dashboard.git
cd shazam-dashboard
npm install
npm run dev
# Open http://localhost:3000