+++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++
+++++                                  ++++++
+++++                                  ++++++
+++++    +++++++++++++++++++++++++++++++++++++++++++++
+++++    +++++++++++++++++++++++++++++++++++++++++++++
+++++    +++++++++++++++++++++++++++++++++++++++++++++
+++++    ++++++                                 ++++++
+++++    ++++++                                 ++++++
+++++    ++++++   +++++++++++++++++++++++++++++++++++++++++++++
+++++    ++++++   +++++++++++++++++++++++++++++++++++++++++++++
+++++    ++++++   +++++++++++++++++++++++++++++++++++++++++++++
+++++    ++++++   ++++++                                  +++++
+++++    ++++++   ++++++                                  +++++
+++++    ++++++   ++++++     +++++++                      +++++
+++++++++++++++   ++++++    +++++++++                     +++++
+++++++++++++++   ++++++    ++++++++++                    +++++
+++++++++++++++   ++++++    ++++++++++                    +++++
         ++++++   ++++++     ++++++++                     +++++
         ++++++   ++++++                                  +++++
         +++++++++++++++                                  +++++
         +++++++++++++++                                  +++++
         +++++++++++++++                                 ++++++
                  ++++++                                 ++++++
                  ++++++                                +++++++
                  +++++++++++++++                      +++++++
                  +++++++++++++++                     +++++++
                  +++++++++++++++                    ++++++++
                            +++++                 +++++++++
                            +++++              ++++++++++
                            +++++++++++++++++++++++++++
                            ++++++++++++++++++++++++
                            ++++++++++++++++++++

Trumbo is a full-stack AI coding agent. It reads your project, plans changes, edits files across your codebase, runs shell commands, browses the web, and reports back, all with you in the loop. It runs four ways from one engine:

• Interactive TUI — terminal chat with Plan/Act modes, slash commands, session trees, live tool approvals, and themes.
• Headless / JSON — pipe a prompt, get styled text or NDJSON events for CI/CD and scripting.
• RPC mode — JSONL over stdin/stdout for embedding Trumbo in editors, orchestrators, and other tools.
• SDK — a TypeScript API (@trumbodev/sdk) for building your own agents, tools, connectors, and scheduled automations.

Bring your own API keys (Anthropic, OpenAI, Google, OpenRouter, Bedrock, Vertex, Azure, Cerebras, Groq, Ollama, LM Studio, or any OpenAI-compatible endpoint), or sign in with a Trumbo account for hosted model access and cloud agent tools.

Install the CLI. @trumbodev/cli ships a native Rust binary for Windows, macOS, and Linux — the per-platform binary is pulled automatically via npm optionalDependencies, so no Node, Bun, or Rust runtime is needed to run it.

# npm / pnpm / bun
npm i -g @trumbodev/cli
pnpm add -g @trumbodev/cli
bun add -g @trumbodev/cli

# curl (macOS / Linux) — no package manager required
curl -fsSL https://raw.githubusercontent.com/xedro98/Trumbo/main/projects/console/script/install.sh | sh

# PowerShell (Windows)
irm https://raw.githubusercontent.com/xedro98/Trumbo/main/projects/console/script/install.ps1 | iex

Then run it in your project:

cd my-project
trumbo                    # interactive TUI
trumbo "fix the tests"    # one-shot prompt
trumbo --json "list TODOs" | jq ...   # headless JSON mode
trumbo --mode rpc         # RPC embedding mode

Or run from source:

git clone https://github.com/xedro98/Trumbo.git
cd Trumbo
bun install
bun --conditions=development --cwd projects/console dev

The agent loop is stateless and streaming-first, designed for reliability and extensibility:

• Two-queue message model — steering messages (delivered before the next assistant response) and follow-up messages (delivered after the agent would stop). Lets you redirect the agent mid-task without interrupting tool execution.
• Parallel tool execution — tools with executionMode: "parallel" run concurrently. File mutations are serialized per-file via a mutation queue (withFileMutationQueue) so concurrent edits to different files don't block each other.
• Retry handling — retries are kept out of the core loop. The provider layer handles transient failures; the session layer auto-retries on auth errors with a force-refresh + restore cycle.
• Truncated tool call safety — when stopReason === "length", all tool calls in the message are failed instead of executing with potentially truncated arguments.
• Cross-provider thinking handoff — when switching models mid-session, thinking/reasoning blocks are automatically converted to portable <thinking> text tags so context is preserved across providers.

The AgentRuntimeHooks interface provides 10 callbacks for extending the agent loop at every decision point:

30 lifecycle events are available for file-based and subprocess hooks, enabling external scripts and automation to react to every stage of the agent lifecycle:

agent_start, agent_resume, agent_abort, agent_end, agent_error, agent_settled, tool_call, tool_result, prompt_submit, pre_compact, session_before_compact, session_shutdown, before_provider_request (read-only), iteration_end, user_bash, context_inject, message_start, message_end, turn_start, turn_end, context_transform, session_branch, model_switch, skill_invoked, command_run, session_fork, session_clone, checkpoint_created, checkpoint_restored, compaction_completed.

Security: The before_provider_request payload is readonly. Extensions can observe but not modify provider requests, keeping billing and auth server-authoritative.

The editor tool uses a fuzzy-match fallback: if the exact old_str isn't found, it searches for the most similar region using Levenshtein distance (0.66 similarity threshold) and replaces it, preserving unchanged lines. This makes edits resilient to minor whitespace or formatting differences between what the model remembers and the actual file state.

Tool output is truncated with a bounded-memory OutputAccumulator (head + rolling tail + temp-file spill). The truncation notice includes Use offset=N to continue reading the elided middle, giving the model an actionable continuation cursor instead of a dead-end "output truncated" message.

When approval is required for an edit, the approval dialog shows a red/green diff of the proposed changes before the file is written. Computed in-memory (no write) by reading the current file content and applying the edit, so you can review exactly what will change before approving.

Sessions auto-save to ~/.trumbo/ organized by working directory.

trumbo -c                  # continue most recent session
trumbo -r                  # browse and select from past sessions
trumbo --no-session        # ephemeral mode (don't save)
trumbo --name "my task"    # set session display name at startup
trumbo --fork <id>         # fork a session into a new one

Sessions are stored as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files. Navigate with /tree, switch branches, and continue from any point. All branches live in a single session file.

• Branch summaries — when switching branches, a summary of the abandoned branch is automatically injected so context is preserved across branch switches.
• Labels — bookmark entries in the tree for quick navigation.
• Fork / clone — /fork creates a new session file from a previous user message; /clone duplicates the current active branch.

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

• Manual: /compact or /compact <focus area>
• Automatic: triggers on context overflow or when approaching the limit.
• Strategies: basic (truncation) or agentic (LLM-generated summaries).
• Split-turn compaction: oversized tool results are truncated mid-turn without losing the conversation flow.

A coordinator agent splits work into subtasks and delegates to specialist agents, each with its own tools and context. 17+ team tools manage the team lifecycle:

• team_spawn_teammate — spawn a specialist with a role prompt
• team_run_task — assign a task to a teammate
• team_await_runs — wait for parallel teammate runs to complete
• team_broadcast — send a message to all teammates
• team_create_outcome — define a success criterion for the mission

Team state persists across sessions, so you can resume a team sprint days later.

trumbo --team-name auth-sprint "Plan and implement user authentication with tests"

Run agents on cron schedules for recurring work. Schedules persist across restarts and run independently of any terminal.

trumbo schedule create "PR summary" \
  --cron "0 9 * * MON-FRI" \
  --prompt "List all open PRs and their review status" \
  --workspace /path/to/repo

trumbo schedule list
trumbo schedule trigger <id>
trumbo schedule history <id>

Chat with your agent from Telegram, Slack, Discord, Google Chat, WhatsApp, or Linear. Each thread maps to an agent session with full context.

trumbo connect telegram -k $BOT_TOKEN
trumbo connect slack --bot-token $SLACK_TOKEN --signing-secret $SECRET --base-url $URL
trumbo connect discord --bot-token $BOT_TOKEN
trumbo connect --stop            # stop all bridges

The hub daemon is a shared WebSocket session server that manages multiple agent sessions. It enables the dashboard, background zen mode (--zen), and connector bridges.

trumbo hub ensure    # start if not running
trumbo hub status    # check status
trumbo hub stop      # stop the daemon
trumbo dashboard     # open the hub dashboard

Embed Trumbo in other tools via newline-delimited JSON over stdin/stdout. Every session operation is available programmatically.

echo '{"type":"start","config":{"providerId":"anthropic","modelId":"claude-sonnet-4"}}' | trumbo --mode rpc

Events are streamed as they happen (agent events, tool calls, tool results, turn boundaries). See the RPC docs for the full protocol.

trumbo auth --provider anthropic --apikey sk-... --modelid claude-sonnet-4
trumbo auth trumbo    # sign in with Trumbo account (device code flow)

Register tools, commands, rules, message builders, providers, MCP servers, and TUI views programmatically. Plugins can run in-process (jiti-loaded TypeScript) or in a subprocess sandbox.

import { Agent, createTool } from "@trumbodev/sdk"

const deployTool = createTool({
  name: "deploy",
  description: "Deploy the current branch to staging.",
  inputSchema: { type: "object", properties: { env: { type: "string" } }, required: ["env"] },
  execute: async (input) => {
    // your deployment logic
  },
})

const agent = new Agent({ tools: [deployTool] })

Capability packages following the Agent Skills standard. Place SKILL.md files in:

• ~/.trumbo/skills/ (global)
• ~/.agents/skills/ (cross-harness standard)
• ~/.claude/skills/ (Claude compatibility)
• ~/.codex/skills/ (Codex compatibility)
• .trumbo/skills/ (project-local, trust-gated)

Invoke with /skill:name or let the agent load them automatically via progressive disclosure.

Connect MCP servers for databases, APIs, cloud infra, and external systems.

trumbo mcp install fs -- npx -y @modelcontextprotocol/server-filesystem /tmp
trumbo mcp install ctx7 --transport http https://mcp.context7.com/mcp

When you sign in with a Trumbo account, the trumbo-platform MCP server is auto-configured with cloud agent tools (agent_create, agent_list, agent_send, etc.) and knowledge search. The bearer token is automatically refreshed at startup, on model change, and on /reload so it never expires while you're signed in.

Drop project rules into .trumbo/ or AGENTS.md / CLAUDE.md — coding standards, architecture conventions, deployment runbooks, testing requirements. They're picked up automatically. Context files are loaded from:

• ~/.trumbo/AGENTS.md (global)
• Parent directories (walking up from cwd)
• Current directory

Before loading project-local extensions, skills, and config, the CLI checks whether you trust the workspace. Trust decisions are stored in ~/.trumbo/trust.json.

trumbo --trust always    # trust this workspace
trumbo --trust never     # don't trust
trumbo --trust ask       # prompt (default)

Create reusable prompt macros in ~/.trumbo/prompts/*.md with $1, $@ positional arguments. Invoke with /templatename args.

Define a subset of models in ~/.trumbo/scoped-models.json and cycle through them with Ctrl+M during a session.

Pipe input, get JSON out, chain commands, wire into pipelines.

trumbo "Run tests and fix any failures"
git diff origin/main | trumbo "Review these changes for issues"
trumbo --json "List all TODO comments" | jq -r 'select(.type == "agent_event" and .event.text) | .event.text'
trumbo --yolo "Refactor this package"    # skip approvals
trumbo --zen "Background task"           # dispatch to hub daemon, exit immediately

import { TrumboCore } from "@trumbodev/sdk"

const trumbo = await TrumboCore.create({
  hub: { cwd: process.cwd(), clientType: "my-app", displayName: "My App" },
})

const { sessionId } = await trumbo.start({
  config: { providerId: "anthropic", modelId: "claude-sonnet-4" },
})

await trumbo.send(sessionId, { prompt: "Explain this codebase" })

// Subscribe to streaming events
trumbo.subscribe((event) => {
  console.log("Event:", event)
})

// Navigate the session tree
const snapshot = await trumbo.tree.getSnapshot(sessionId)
await trumbo.tree.switchLeaf(sessionId, entryId)

The SDK exposes session lifecycle, tree navigation (trumbo.tree), tool orchestration, hooks, plugins, and the hub daemon. See the SDK docs for the full API.

The terminal interface (built on OpenTUI + React) provides:

• Plan / Act modes — Tab to toggle between read-only exploration and execution
• Session tree navigation — /tree to browse branches, switch leaves, label bookmarks
• Slash commands — 22+ built-in: /tree, /fork, /clone, /compact, /model, /undo, /trust, /scoped-models, /reload, /hotkeys, /changelog, plus plugin/skill/prompt commands
• Steering + follow-up queue — queue messages while the agent is working (Enter = steer, Alt+Enter = follow-up)
• Checkpoints — /undo rewinds chat and workspace state via git-stash
• Tool approvals — approve/deny each tool call with optional pre-execution diff preview
• Themes — 5 built-in (dark, light, dracula, nord, solarized) + custom ~/.trumbo/themes/*.json with hot-reload
• Keybindings — customizable via ~/.trumbo/keybindings.json

npm install -g @trumbodev/cli@latest

On Windows, close any running Trumbo sessions before upgrading. If you hit EBUSY or EPERM:

Get-Process trumbo -ErrorAction SilentlyContinue | Stop-Process -Force
npm install -g @trumbodev/cli@latest --allow-scripts=@trumbodev/cli

The --allow-scripts=@trumbodev/cli flag lets the postinstall cache the binary outside node_modules for smoother Windows upgrades. The launcher version-checks its cache on every start, so a stale cached binary can never shadow a fresh npm install.

See the upgrade guide for full details.

Read the Contributing Guide. Open an issue or start a discussion if you want to help.

Apache 2.0