#DevBoy tools

A research-driven tool bundle for AI coding agents. A single curated set of dev-workflow tools (GitHub, GitLab, Jira, ClickUp, Confluence, Slack, Fireflies) reachable from any agent — Claude Code, Copilot CLI, Codex, Cursor, Kimi, Gemini, … — through three transports: MCP server, CLI, or installable agent skills. Output goes through a token-aware pipeline that compresses responses by 26–69% per call on the data-shape-friendly endpoints it targets (issues, pipelines, large lists) — see paper 2 measurements on a 144k-event production corpus.

npm install -g @devboy-tools/cli   # binary for your platform
devboy onboard                     # detects your AI agent, installs the right skills

That's it. Verify with devboy doctor.

#Why DevBoy

DevBoy isn't another aggregator with a long tool list. Four things that aren't standard elsewhere:

• Research-driven. Every optimisation in the pipeline traces back to a paper grounded in a real corpus — 523 Claude Code sessions, 10,644 MCP tool responses. We don't ship a heuristic without measuring it. See research index.
• Three transports, one bundle. The exact same tool set is reachable as MCP server, CLI for humans / CI, or as agent skills that call individual tools. Pick whichever fits today; layer the rest later.
• Privacy by default. Tokens live in OS keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service) with env-var fallback for CI. No cloud round-trip just to authenticate.
• Multi-project context. One server, many project contexts (different GitHub/GitLab/Jira combinations), instant switch — no respawn, no config edit. Concrete: devboy context use dashboard and the same MCP session now talks to a different project's APIs.

#Quick start (60 seconds)

# 1. Install
npm install -g @devboy-tools/cli

# 2. Bootstrap — picks your agent + installs a curated skill bundle
devboy onboard

# 3. Configure your first provider (interactive)
devboy init

# 4. Verify
devboy doctor

After this devboy issues returns your open tickets, your agent has the relevant skills loaded, and the MCP server is registered with whatever client you use.

#Install via plugin (Claude Code / Codex CLI)

If you live inside Claude Code or Codex CLI, skip the npm step entirely.

Claude Code:

/plugin marketplace add meteora-pro/devboy-tools
/plugin install devboy@meteora-devboy

Codex CLI — reads the same .claude-plugin/marketplace.json (one of the four official marketplace sources), so the install is symmetric:

codex plugin marketplace add meteora-pro/devboy-tools
codex plugin install devboy@meteora-devboy

Either way, the bundled setup skill installs the devboy CLI on first use (npm install -g with a SHA-256-verified GitHub Release tarball as fallback), wires up the MCP server, and runs devboy onboard. After the binary lands, run /reload-plugins (Claude Code) or restart your Codex session once.

OpenCode and Kimi CLI users get the same skills for free — both auto-read ~/.claude/skills/, so installing the Claude Code plugin or running devboy onboard covers them too. See the per-agent guides (Claude Code, Codex) and ADR-018 for the architecture.

If you'd rather pick everything by hand:

# Configure GitHub (replace gitlab/clickup/jira similarly)
devboy config set github.owner meteora-pro
devboy config set github.repo devboy-tools
devboy config set-secret github.token <token>     # → OS keychain

# Or via env vars (CI / Docker — keychain unavailable)
export DEVBOY_GITHUB_TOKEN=ghp_...
# Compatibility: GITHUB_TOKEN is read too

# Pick skills explicitly instead of using a profile
devboy skills list
devboy skills install review-mr --agent claude
devboy skills install --all --agent all

git clone https://github.com/meteora-pro/devboy-tools.git
cd devboy-tools && cargo build --release
./target/release/devboy --version

#Skills & onboarding

DevBoy ships a catalogue of skills — one-page Markdown recipes that tell an AI agent how to use the bundle to accomplish a common task. Skills are CLI-first (devboy tools call <name> under the hood), agent-agnostic (Claude Code / Codex / Cursor / Kimi or a vendor-neutral path), and versioned with the binary.

devboy onboard is the fastest path: it scans ~/.claude/, ~/.copilot/, ~/.codex/, ~/.kimi/, Cursor's storage, ~/.gemini/, and ~/.gemini/antigravity/, scores each agent on freshness × volume (recency wins ties), and installs a profile-specific bundle.

devboy onboard                          # auto-detect + install `dev` bundle
devboy onboard --profile pm             # PM bundle (issues + meetings + chat)
devboy onboard --profile oncall         # diagnostics + notifications
devboy onboard --agent kimi --yes       # explicit agent + non-interactive
devboy agents list                      # show all detected agents with score

Three profiles ship today; categories below cover the full catalogue.

Skill installs keep a per-location manifest with SHA-256s so upgrades leave user-modified files alone (ADR-014). Self-feedback skills read session traces from .devboy/sessions/ (ADR-015).

analyze-usage is a featured skill that ships in two parts: a thin baseline (one Markdown file, embedded in the binary) plus a heavier Python backend (~1 MB, sparse-checked-out via curl on first use). It produces graphic monthly / weekly digests of how your AI sessions actually went — biome aquariums, 8-archetype bars, DORA radar, friction markers — plus shareable anonymised parquet bundles. See ./.claude/skills/analyze-usage/.

#Three integration modes

The same tool set, three transports — pick what your workflow already uses.

JSON arguments tip. devboy tools call <name> takes an optional positional JSON string (defaults to {}). POSIX shells: wrap in single quotes. Windows cmd.exe/PowerShell: escape inner quotes — devboy tools call get_issues "{\"limit\": 20}".

#Claude Code

The fastest way to get started is devboy onboard — it auto-detects which AI agent you actively use (by scanning ~/.claude/, ~/.copilot/, ~/.codex/, ~/.kimi/, Cursor's storage, ~/.gemini/, ~/.gemini/antigravity/) and installs a curated skill bundle for that agent:

devboy onboard                              # detect primary agent, install the `dev` bundle
devboy onboard --profile pm                 # PM bundle (issue tracking + meetings + messenger)
devboy onboard --profile oncall             # on-call bundle (diagnostics + notifications)
devboy onboard --agent kimi --yes           # explicit agent + non-interactive (CI / dotfiles)
devboy agents list                          # show all detected agents with sessions / last-used / score

If you'd rather pick skills by hand:

claude mcp add devboy -- devboy mcp
claude mcp list

#Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "devboy": { "command": "devboy", "args": ["mcp"] } } }

For Codex / Cursor / Kimi / Copilot CLI / Gemini CLI / Antigravity — devboy onboard autoconfigures the MCP entry; or follow the agent's docs for adding a stdio MCP server pointing at devboy mcp.

#Providers

Seven provider plugins ship today — each with a dedicated client + schema enricher so the tool list adapts to your project's actual fields (custom fields, enum values, status taxonomies):

Adding a provider is a Rust crate implementing Provider + a ToolEnricher (ADR-007).

#Secret management

Provider tokens, deploy keys, API tokens — devboy-tools ships a first-class secret framework so values never sit in plaintext config files and AI agents never see raw values.

• Manifest-driven — projects declare required and optional secrets in .devboy/secrets.toml (ADR-020). The merged inventory is the source of truth for secrets list, doctor, and the inventory view.
• Pluggable sources — keychain, local-vault, 1Password, Vault (HTTP KV v2), env-store ship in-tree; community plugins extend the set via a stdio JSON-RPC subprocess protocol (ADR-021).
• Native UI — TUI on ratatui + GUI on egui sharing one view-model layer; backend autodetected from $DISPLAY/$WAYLAND_DISPLAY (ADR-023 §3.4).
• Agent-safe by construction — MCP secrets_* tools return metadata only. Trust boundary is enforced by a marker trait, a CI grep gate, and a sentinel-based negative test (ADR-023 §3.7).
• Three deployment modes — desktop (OS keychain), team (local-vault), CI (env-store). End-to-end smoke tests cover all three on every PR.

Four guides for the framework live under docs/guide/secrets/:

• Onboarding — manual install → first source → manifest → validate → doctor.
• Local Vault — file format, recovery flow, backup recommendations.
• Agent Protocol (MCP) — every secrets_* tool, examples, the "no secrets.get" rule.
• Source Plugin Protocol — stdio JSON-RPC reference + working echo-source example in examples/secrets-source-echo/.

devboy secrets list                # see what the active context expects
devboy doctor --secrets            # is everything provisioned?
devboy secrets ui                  # TUI/GUI inventory
devboy secrets rotate <path>       # opens provider URL + prompts for new value

For AI-driven setup, point the agent at the setup-secrets skill — it walks the eight-step wizard with a state file at ~/.devboy/secrets/setup-state.toml.

#Research

Every non-trivial optimisation in the pipeline is backed by a paper grounded in a real corpus — 523 Claude Code sessions, 10,644 MCP responses from production traffic. The full docs/research/INDEX.md tracks methods, datasets, and reproducibility scripts.

Other corpus baselines used across papers (the 523 Claude Code sessions / 10,644 MCP-response sample, paper 1 §B):

• get_merge_request_diffs: P90 = 35 k chars ≈ 10 k tokens — 28% of responses exceed an 8 k-token budget
• get_epics: P90 = 43 k chars ≈ 12 k tokens — 37% exceed budget
• After overflow, agents always produce a text response on the next turn — they never retry / paginate (paper 1 §3, paper-1-trimtree.md:30 and §C)

Paper 3's prefetch dispatcher already runs in the format pipeline; papers 1 and 2 land in the next minor version. Paper 4 is at concept stage — no production code yet.

#Architecture

crates/
├── devboy-core/        Traits (Provider, ToolEnricher), shared types, config
├── devboy-executor/    Tool execution engine + enrichment pipeline
├── devboy-mcp/         MCP server (JSON-RPC over stdio)
├── devboy-cli/         CLI binary (`devboy`)
├── devboy-skills/      Skill catalogue, install/upgrade, manifests, traces
├── devboy-storage/     Credential storage (keychain, env vars)
├── devboy-assets/      File attachments (ADR-010)
└── plugins/
    ├── api/            { github, gitlab, jira, clickup, slack, fireflies }
    └── format-pipeline The token-aware output pipeline (papers 1, 2, 3)

┌─ DevBoy MCP / CLI ────────────────┐
│  context: devboy-tools             │
│    ├── GitHub: meteora-pro/devboy  │
│    └── Slack: #devboy              │
│  context: dashboard                │
│    ├── GitLab: project #42         │
│    ├── ClickUp: list abc123        │
│    └── Jira: DEV                   │
└────────────────────────────────────┘

Tool call → Executor
  1. Enrichers transform args   (e.g. cf_story_points → customFields)
  2. Provider factory builds the client from ProviderConfig
  3. Provider executes API calls → typed ToolOutput
  4. Format pipeline encodes output → text (markdown / compact / json)

#Documentation map

• Getting started — docs/guide/getting-started/
• CLI reference (auto-generated) — docs/guide/reference/cli.md
• Tool reference (auto-generated) — docs/guide/reference/tools.md
• Skills user guide — docs/guide/skills/
• Configuration (env vars, contexts, doctor, proxy, format pipeline) — docs/guide/configuration/
• Secret management (onboarding, local-vault, agent protocol, source plugins) — docs/guide/secrets/
• Architecture — docs/guide/architecture/
• ADRs — docs/architecture/adr/INDEX.md (18 decisions logged)
• Research papers — docs/research/INDEX.md
• Release procedure — docs/guide/contributing/release.md

#Use as a library

Beyond the CLI, the workspace ships library crates on crates.io — embed devboy components directly in a Rust project. The catalogue covers the foundation, credential storage, the format pipeline, every API provider, the MCP server, the skills subsystem, and the CLI binary.

Crate	Description	Crates.io	Docs
devboy-core	Provider traits, unified types, configuration, errors
devboy-storage	OS-keychain credential storage with SecretString plumbing
devboy-assets	On-disk asset cache with LRU rotation (ADR-010)
devboy-format-pipeline	TOON encoding, MCKP-budget trimming, cursor pagination
devboy-gitlab	GitLab provider (issues, merge requests)
devboy-github	GitHub provider (issues, pull requests)
devboy-jira	Jira provider (issues, project versions)
devboy-clickup	ClickUp provider
devboy-confluence	Confluence (self-hosted) provider
devboy-fireflies	Fireflies meeting transcripts
devboy-slack	Slack provider
devboy-executor	Tool execution engine + provider factory
devboy-mcp	MCP server (JSON-RPC 2.0 over stdio)
devboy-skills	Skills subsystem (SKILL.md parser, install lifecycle)
devboy-cli	The devboy CLI binary (npm is the primary channel)

Example — embed a single provider:

[dependencies]
devboy-core = "0.26"
devboy-jira = "0.26"

// Illustrative — not run automatically.
use devboy_core::{Config, IssueProvider};
use devboy_jira::JiraClient;
use secrecy::SecretString;

async fn embed() -> anyhow::Result<()> {
    let cfg = Config::load()?;
    let jira_cfg = cfg.jira.expect("jira section missing in .devboy.toml");

    // In a real devboy setup the token comes from the OS keychain via
    // `devboy_storage::ChainStore`; for an embedded host pass any
    // `SecretString` source you trust.
    let token: SecretString = std::env::var("JIRA_TOKEN")?.into();

    let client = JiraClient::new(
        jira_cfg.url,
        jira_cfg.project_key,
        jira_cfg.email,
        token,
    );

    let issue = client.get_issue("PROJ-123").await?;
    println!("{}", issue.key);
    Ok(())
}

The release procedure is documented in docs/guide/contributing/release.md. See ADR-022 for the architectural decision behind the dual npm + crates.io distribution.

#Development

cargo build                        # debug build
cargo test                         # runs the workspace test suite
cargo clippy --all-targets         # lint (CI uses RUSTFLAGS=-Dwarnings)
cargo fmt --all                    # format
cargo run -p devboy-cli -- doctor  # smoke

The CLI reference is gated in CI: after touching clap definitions, run

cargo run -p devboy-cli -- docs cli --output docs/guide/reference/cli.md

so the committed reference matches the binary. Same idea for devboy tools docs and the tool reference.

See CONTRIBUTING.md for the full guide (commit conventions, branch naming, ADR workflow, release process).

#Community

• Issues / feature requests — GitHub Issues
• Design discussions — GitHub Discussions
• Code review tooling — open a PR; CI runs Format, Clippy, Test on macOS / Linux / Windows, Coverage, and the docs drift gate

#License

Apache License 2.0 — use it, modify it, ship it; if you build something interesting on top, we'd love a heads-up via Discussions.