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

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

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"

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

Installation

Prerequisites

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

Install binaries

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

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

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

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

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

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

briefkit-ctl setup [flags]

briefkit-ctl state execution list

briefkit-ctl state execution show <execution-id>

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

Troubleshooting

License

MIT License. See LICENSE.