phone-a-friend: Instructions file for Claude Code

AGENTS.md

Guidance for AI coding agents working in phone-a-friend.

What This Is

phone-a-friend is a TypeScript CLI for relaying prompts + repository context to coding backends (Claude, Antigravity, Codex, Gemini, Ollama, OpenCode). Available via npm install -g @freibergergarcia/phone-a-friend or from source. All backend run() methods are async (Promise<string>). Backends may also implement runStream() returning AsyncIterable<string> for token-level streaming.

Project Structure

src/
  index.ts           Entry point — imports backends, runs CLI
  cli.ts             Commander.js CLI with subcommands
  relay.ts           Backend-agnostic relay core (relay + relayStream + reviewRelay)
  stream-parsers.ts  Stream parsers — SSE (OpenAI-compatible), NDJSON (Ollama), Claude JSON snapshots
  context.ts         RelayContext interface
  version.ts         Shared version reader
  detection.ts       Backend detection (CLI, Local, Host)
  config.ts          TOML configuration system
  doctor.ts          Health check command
  diagnostics.ts     PATH/executable identity and bounded version probes for doctor
  setup.ts           Interactive setup wizard
  installer.ts       Claude/OpenCode host integration installer (symlink/copy)
  theme.ts           Shared semantic theme (chalk) for CLI styling + banner
  display.ts         Display helpers (mark, formatBackendLine)
  jobs.ts            Background job manager (JSON persistence at ~/.config/phone-a-friend/jobs.json)
  sessions.ts        Relay session store (JSON persistence at ~/.config/phone-a-friend/sessions.json)
  tasks.ts           Task store (SQLite at ~/.config/phone-a-friend/tasks.db): durable records + events for every relay/review
  task-tracking.ts   Bridges one CLI run to the task store (RelayObserver, retention modes, drift warning)
  progress.ts        Progress reporter: observer hooks -> stderr lines or spinner text, plus the end-of-run receipt
  status-line.ts     One-row status for Claude Code's status line (running or recently finished task for the cwd repo)
  backends/
    index.ts         Backend interface, registry, types, BackendCapabilities, spawnCli() async subprocess utility
    antigravity.ts  Google Antigravity CLI subprocess backend (`agy`, read-only, one-shot)
    claude.ts        Claude CLI subprocess backend (`claude -p`)
    codex.ts         Codex subprocess backend
    gemini.ts        Gemini subprocess backend
    ollama.ts        Ollama HTTP API backend (native fetch)
    opencode.ts      OpenCode CLI subprocess backend (`opencode run`, agentic with tool calling)
  agentic/
    index.ts         Public API — Orchestrator, TranscriptBus exports
    types.ts         AgentConfig, AgenticSessionConfig, AgentState, Message, AGENTIC_DEFAULTS
    orchestrator.ts  Main loop — spawn agents, route messages, guardrails, emit events
    session.ts       SessionManager — Claude CLI subprocess with UUID-based sessions
    bus.ts           SQLite transcript bus (better-sqlite3) — append-only session log
    queue.ts         In-memory MessageQueue for runtime routing
    events.ts        AgenticEvent discriminated union + EventChannel (push/pull bridge)
    parser.ts        @mention extraction + system prompt builder
    names.ts         Creative agent name assignment (e.g., ada.reviewer)
  tui/
    App.tsx          Root TUI component — tab bar + panel routing
    render.tsx       Ink render entry point
    StatusPanel.tsx  System info + backend detection display
    BackendsPanel.tsx Per-backend list with detail pane
    ConfigPanel.tsx  Config view + inline editing
    ActionsPanel.tsx Async-wrapped executable actions
    AgenticPanel.tsx Session browser with list view
    hooks/
      useDetection.ts    Async detection with throttled refresh
      usePluginStatus.ts Host integration install status (sync FS check)
      useAgenticSessions.ts  SQLite session loader for Agentic panel
    components/
      TabBar.tsx             Tab navigation bar
      PluginStatusBar.tsx    Persistent host integration install indicator
      Badge.tsx              Status badges (✓ ✗ ! ·)
      KeyHint.tsx            Footer keyboard hints
      ListSelect.tsx         Scrollable selectable list
tests/               Vitest tests (mirrors src/ structure, includes spawn-cli, jobs, background-relay)
commands/<name>.md   Rich Claude Code slash commands (full workflow, argument-hint, Gemini model selection, etc.)
agents/paf-reviewer.md   Claude plugin subagent (background, Bash+Read, sonnet): runs one PaF command and reports receipt + verbatim findings
skills/<name>/SKILL.md         Canonical Agent Skills — primary OpenCode entry point, also auto-discovered by Claude Code as plugin-namespaced skills
skills/<name>/COMMAND.opencode.md  Thin OpenCode command shim (overlay). Installer prefers this over commands/<name>.md when present, so OpenCode users get a small shim that delegates into SKILL.md while Claude users get the rich commands/<name>.md inline.
dist/                Built bundle (committed, self-contained)