OrbiqD BriefKit

Overview

BriefKit runs your local, subscription-based agent CLIs (no APIs or API keys) directly in your working directory or an isolated copy of any local project. It ships as a single, self-contained CLI and an MCP server, with no Python/JS and no extra runtimes. Agents see your repository the same way you do, with no uploads and no remote context copying. BriefKit supports workflows where more than one LLM collaborates in the same workspace.

Currently supported local agent CLIs are claude, codex, gemini.

Usage

As a CLI

Agent-to-agent context handoff

Let Codex analyze a module, then ask Gemini to confirm or expand the findings from the same repo.

briefkit-ctl ask codex "Map the auth flow and list risk points"
briefkit-ctl ask gemini "Validate Codex findings and propose improvements"

Agent challenge

Run the same prompt across agents and compare viewpoints.

briefkit-ctl ask claude "Review this PR for design issues"
briefkit-ctl ask codex "Review this PR for design issues"
briefkit-ctl ask gemini "Review this PR for design issues"

Cross-agent review

Have one agent review work produced by another.

briefkit-ctl ask codex "Refactor the parser to reduce allocations"
briefkit-ctl ask claude "Review the parser refactor for correctness and style"

As an MCP Server

Note: You don't start briefkit-mcp manually. briefkit-ctl setup registers BriefKit as an MCP server using the stdio transport, so your runtime (e.g. Claude Code) spawns it on demand.

Installation

Prerequisites

At least one agent CLI installed and available on your PATH (claude, codex, gemini).

Install binaries

Linux (.deb)

Requires curl, jq, and dpkg.

arch=$(uname -m); case "$arch" in x86_64|amd64) arch=amd64 ;; aarch64|arm64) arch=arm64 ;; *) echo "Unsupported arch: $arch" >&2; exit 1 ;; esac; \
url=$(curl -sL https://api.github.com/repos/orbiqd/orbiqd-briefkit/releases/latest | jq -r ".assets[] | select(.name | endswith(\"linux_${arch}.deb\")) | .browser_download_url" | head -n1); \
curl -L -o /tmp/briefkit.deb "$url" && sudo dpkg -i /tmp/briefkit.deb

Linux (.rpm)

Requires curl, jq, and rpm.

arch=$(uname -m); case "$arch" in x86_64|amd64) arch=amd64 ;; aarch64|arm64) arch=arm64 ;; *) echo "Unsupported arch: $arch" >&2; exit 1 ;; esac; \
url=$(curl -sL https://api.github.com/repos/orbiqd/orbiqd-briefkit/releases/latest | jq -r ".assets[] | select(.name | endswith(\"linux_${arch}.rpm\")) | .browser_download_url" | head -n1); \
curl -L -o /tmp/briefkit.rpm "$url" && sudo rpm -i /tmp/briefkit.rpm

Linux (tarball to /usr/bin)

Requires curl, jq, and tar.

arch=$(uname -m); case "$arch" in x86_64|amd64) arch=amd64 ;; aarch64|arm64) arch=arm64 ;; *) echo "Unsupported arch: $arch" >&2; exit 1 ;; esac; \
url=$(curl -sL https://api.github.com/repos/orbiqd/orbiqd-briefkit/releases/latest | jq -r ".assets[] | select(.name | endswith(\"linux_${arch}.tar.gz\")) | .browser_download_url" | head -n1); \
tmpdir=$(mktemp -d) && curl -L -o "$tmpdir/briefkit.tar.gz" "$url" && tar -xzf "$tmpdir/briefkit.tar.gz" -C "$tmpdir" && \
sudo install -m 0755 "$tmpdir/briefkit-ctl" /usr/bin/briefkit-ctl && \
sudo install -m 0755 "$tmpdir/briefkit-mcp" /usr/bin/briefkit-mcp && \
sudo install -m 0755 "$tmpdir/briefkit-runner" /usr/bin/briefkit-runner

Homebrew (macOS)

brew tap orbiqd/briefkit
brew install briefkit

Agent discovery and MCP setup

Run setup to discover local agent CLIs, create configs, and register the MCP server with supported runtimes. This lets you ask Claude Code to run Codex, for example.

briefkit-ctl setup

Ask your first prompt.

briefkit-ctl ask codex "Explain the architecture of this repo."

Setup options you may need:

• --runtime-kind claude|codex|gemini to limit configuration to specific runtimes
• --setup-agent-mcp=false to skip MCP server registration
• --force to overwrite existing agent configs
• --enable-sandbox=true|false to override runtime sandbox defaults

Configuration and Paths

Default paths:

• Agent configs: ~/.orbiqd/briefkit/agents
• State store: ~/.orbiqd/briefkit/state
• Workspace runs: ~/.orbiqd/briefkit/state/workspaces/runs
• Runtime logs: ~/.orbiqd/briefkit/logs/runtime

Override paths with environment variables:

• BRIEFKIT_AGENT_CONFIG_PATH
• BRIEFKIT_STATE_PATH
• BRIEFKIT_RUNTIME_LOG_DIR

Example agent config (~/.orbiqd/briefkit/agents/codex.yaml):

runtime:
  kind: codex
  config:
    requireWorkspaceRepository: false
  feature:
    enableSandbox: false
timeout: 5m

The timeout field is optional. When omitted, it defaults to 5m. The --timeout flag in briefkit-ctl ask overrides this value.

Runtime kinds:

• claude
• codex
• gemini

briefkit-ctl setup creates configs at ~/.orbiqd/briefkit/agents/<agent-id>.yaml.

MCP Server

Start the MCP server:

briefkit-mcp

By default, briefkit-ctl setup registers the MCP server with supported runtimes. Use --setup-agent-mcp=false to skip registration.

Workspaces

A workspace provides an agent with an isolated, writable copy of a codebase. The original source is never modified. After the execution finishes, the temporary copy is removed automatically.

Without a workspace, the agent runs directly in the current working directory.

Execution states

When a workspace is used, the execution goes through an additional state:

created → started → provisioning → running → succeeded / failed

The provisioning state covers the time spent preparing the workspace (copying files or cloning a repository). For large git repositories this can take a while — the state makes it visible.

Providers

No workspace (default)

The agent runs in the current working directory. Files are read and written directly.

briefkit-ctl ask codex "Explain the auth module."

---

dir:// — local directory copy

Copies a local directory into a fresh per-execution directory under ~/.orbiqd/briefkit/state/workspaces/runs/. The agent sees an exact copy of the source; changes it makes stay in the copy and are discarded at cleanup.

dir:///absolute/path/to/project

briefkit-ctl ask claude --workspace "dir:///home/user/myproject" "Review the API surface."

Use this when you want to point an agent at a project that is not your current directory, or when you want to protect a local directory from agent writes.

---

git+https:// — remote git repository over HTTPS

Clones a public or private git repository into a fresh per-execution directory. Auth relies on the user's existing git credential helpers, .netrc, and ~/.gitconfig. No API keys or extra configuration needed.

git+https://github.com/org/repo.git
git+https://github.com/org/repo.git?ref=main
git+https://github.com/org/repo.git?ref=v2.1.0
git+https://github.com/org/repo.git?ref=abc1234

The optional ref query parameter selects a branch, tag, or commit. When omitted, the repository's default branch is used.

# Default branch
briefkit-ctl ask claude --workspace "git+https://github.com/golang/example.git" "Describe this repo."

# Specific branch
briefkit-ctl ask codex --workspace "git+https://github.com/org/repo.git?ref=feature/payments" "Review the payments module."

# Specific tag
briefkit-ctl ask gemini --workspace "git+https://github.com/org/repo.git?ref=v2.1.0" "What changed in this release?"

---

git+ssh:// — remote git repository over SSH

Same as git+https:// but uses SSH. Auth relies on the user's SSH agent (SSH_AUTH_SOCK) and key files. No extra configuration needed if SSH access to the host already works in your terminal.

git+ssh://git@github.com/org/repo.git
git+ssh://git@github.com/org/repo.git?ref=main

briefkit-ctl ask claude --workspace "git+ssh://git@github.com/org/private-repo.git" "Summarize the architecture."

---

MCP Server

When using BriefKit as an MCP server, the workspace parameter is available on every ask_* tool. The same URI formats apply.

CLI Manual

briefkit-ctl

Usage:

briefkit-ctl [global flags] <command>

Global flags:

• -v, --log-level (debug|info|warn|error, default: info)
• --log-format (text-color|text-no-color|json, default: text-color)
• --log-quiet (disable logging)
• -s, --store-state-path (default: ~/.orbiqd/briefkit/state)
• --store-agent-config-path (default: ~/.orbiqd/briefkit/agents)
• --version (print version)

briefkit-ctl agent list

Lists configured agents (JSON output).

briefkit-ctl agent list

briefkit-ctl agent add

Adds a new agent entry. Note: currently not implemented.

briefkit-ctl agent add <id> <kind> <path>

Kind values: claude, codex, gemini.

briefkit-ctl ask

Runs a prompt with a configured agent.

briefkit-ctl ask [flags] <agent-id> <prompt>

Flags:

• --timeout (duration, e.g. 30s, 5m)
• --model (override model)
• --conversation-id (continue a conversation)
• --workspace (workspace URI; see Workspaces for supported schemes and examples)

briefkit-ctl setup

Auto-discovers local agent CLIs, creates configs, and optionally registers the MCP server with supported runtimes.

briefkit-ctl setup [flags]

Flags:

• --runtime-kind (repeatable; one of claude, codex, gemini)
• --setup-agent-config (default: true)
• --setup-agent-mcp (default: true)
• --enable-sandbox (set true or false to override defaults)
• --force (overwrite existing configs)

briefkit-ctl state execution list

Lists stored executions (JSON output).

briefkit-ctl state execution list

briefkit-ctl state execution show

Shows details for a single execution (JSON output).

briefkit-ctl state execution show <execution-id>

briefkit-ctl state execution create

Creates a new execution record (advanced use; JSON output with execution ID).

briefkit-ctl state execution create --agent-id <id> [flags] <prompt>

Flags:

• -w, --workspace (workspace URI, e.g. dir:///path/to/project)
• -t, --timeout (default: 5m)

Troubleshooting

Problem: `briefkit-ctl setup` does not find your agent CLI.

• Verify the agent binary is in your PATH (which claude, which codex, which gemini).

Problem: `briefkit-ctl ask` fails with missing agent config.

• Run briefkit-ctl setup and confirm the agent appears in briefkit-ctl agent list.

Problem: MCP tools do not appear in your client.

• Ensure the MCP client points to the absolute path of briefkit-mcp.
• Restart the MCP client after config changes.

License

MIT License. See LICENSE.