Warning
Pre-alpha. Commands, flags, config schema, and on-disk layout may change between any two installs without warning. See Installation before using.
A command-line tool for managing agentic coding workflows. Bespoke provides a professional, reproducible, and secure execution environment for AI coding agents working on software projects.
Most agentic coding setups run the agent locally with full access to the host machine — the same privileges as the user, the same filesystem, the same credentials. This creates security exposure and tight coupling between the LLM, the agent, the project, and the machine.
Bespoke treats agents like any other developer on a team. Just as a new human developer is given a machine, a repository, documentation, and a bootstrap script to get started — an agent gets the same. The host machine's configuration is irrelevant; Bespoke keeps the host, the execution environment, and the project completely decoupled.
Think of it as infrastructure management (like Ansible or Chef) applied to development workflow architecture. Bespoke is not an IDE replacement. It is the layer that gives agents a clean, consistent, auditable place to work.
Bespoke is built around three decoupled primitives.
Defines the container topology the agent executes inside: OS packages, networking, workspace
mounts. Specified by a Dockerfile and optional docker-compose.yml. The runtime has no
knowledge of agents, models, or projects — it defines a ceiling of what is available.
The runtime answers: what does the execution environment look like?
Defines how Bespoke behaves in a given context: which agent and model to use, where to find docs
and initialization scripts, what information sources the agent may consult, and which runtime to
use. Profiles can be host-managed ($BESPOKE_HOME/profiles/) or project-managed
(.bespoke/profile.toml in the repository).
The profile answers: how does the agent work in this context?
The directory being worked on. Mounted into the runtime at /workspace/src. Bespoke makes no
assumptions about structure or version control. A repository doesn't need to know anything about
Bespoke to be a valid target.
The repo answers: what is the agent working on?
bespoke run [--profile <name>] <repo-path>
│ │
│ └── repo: mounted at /workspace/src
└── profile: agent, model, docs path, bootstrap path
└── runtime: container topology
The only supported install path is go install,
which means you'll need Go 1.23+ on your machine:
go install github.com/chrisburnor/bespoke@latestThis drops a bespoke binary in $(go env GOBIN) (or $(go env GOPATH)/bin
if GOBIN is unset). Make sure that directory is on your PATH.
To confirm the install and capture build info for bug reports:
bespoke versionBespoke is currently open for use by brave go developers who would like to try it out while its in development.
- No versioning. There are no release tags.
go install …@latestresolves to the tip ofmain(as a pseudo-version), and what you get today may behave differently from what you got yesterday. - No backwards-compatibility guarantee. Between any two installs, command
names, flags, config schema, and on-disk layout under
$BESPOKE_HOMEmay all change without warning. Expect to re-scaffold profiles and runtimes after upgrading. - No prebuilt binaries, no homebrew, no curl-pipe-sh installer. These will come later. For now the audience is potential contributors (i.e. Go developers who can build from source.)
When filing a bug, include the output of bespoke version so the commit SHA
identifies which build you were running.
# Scaffold a runtime
bespoke runtime new my-runtime
# Scaffold a profile
bespoke profile new my-profile
# Run an agent against a repository
bespoke agent run --profile my-profile ~/projects/my-repo
# Open an interactive shell in the runtime
bespoke agent shell --profile my-profile ~/projects/my-repo$BESPOKE_HOME/ # default: ~/.config/bespoke
config.toml # global defaults
profiles/
<profile-name>/
profile.toml
runtimes/
<runtime-name>/
Dockerfile
docker-compose.yml # optional
A project-managed profile lives inside the repository:
<repo-root>/
.bespoke/
profile.toml # project-managed profile
docs/ # project context (for humans and agents)
bootstrap.sh # environment initialization script
When bespoke run is invoked, the active profile is resolved as follows:
--profile <name>CLI flag.bespoke/profile.tomlin the repository$BESPOKE_HOME/profiles/<inferred-name>/profile.toml- Global defaults from
$BESPOKE_HOME/config.toml
| Variable | Default | Purpose |
|---|---|---|
$BESPOKE_HOME |
~/.config/bespoke |
Global Bespoke configuration directory |
# $BESPOKE_HOME/config.toml — global defaults
[defaults]
agent = "claude-code"
runtime = "base"# .bespoke/profile.toml — project-managed profile
runtime = "rust-base"
agent = "claude-code"
model = "claude-sonnet-4-5"
[bootstrap]
path = "./bootstrap.sh"
[docs]
path = "./docs"Any repository intended for agentic development should provide a bootstrap.sh script that
installs project-level dependencies (language toolchains, virtual environments, OS packages,
services, etc.). The bootstrap script runs inside the runtime as a privileged user, separate from
the agent user.
This replaces the fragile convention of listing setup steps in a README and is good practice for human developers too.
Security and isolation — Agents run in containers with minimum required privileges. The host filesystem is only accessible through explicitly defined mounts. Secrets are injected via environment variables, never baked into images or config files.
Agent-agnostic architecture — The repository never knows which agent is being used. The integrated agent today is Claude Code; additional agents are designed for but not yet wired up (see below). Models are configured per profile.
The following are described in the design but not yet implemented. They are listed here so the intended shape of the project is visible — not as claims about current behavior.
- Parallelization — multiple agents working on the same repository simultaneously, each on its own branch, submitting work for human review before merging.
- Structured escalation — configurable retry counts and token budgets per task; agent escalates with a structured report when budgets are exceeded rather than looping indefinitely.
- Cost controls — per-session and per-task token budgets enforced at runtime.
- Rate limiting — agent pauses when approaching configured rate-limit thresholds and informs the user.
- Information source control — configured allowlist of authoritative documentation sources the agent may consult, with a broader-access "architect mode" for planning tasks.
- Audit trail — structured per-session log of actions, decisions, and tokens consumed.
- Additional agent integrations — Codex CLI, Hermes, and other agents beyond Claude Code.
- Claude Code (default — the only agent with concrete integration today)
Other agents (Codex CLI, Hermes) are part of the design but are not yet integrated.
/workspace/
src/ # repository mounted here (read-write)
work/ # agent working directory
/home/agent/
# dotfiles loaded from the runtime definition
- General-purpose agent access (email, messaging, documents, social accounts, etc.)
- Any graphical interface — Bespoke is a purely command-line tool
- Replacing or reimplementing agents — Bespoke wraps and configures existing agents
- Prescribing repository structure beyond minimal conventions for docs and bootstrap
MIT © 2026 Chris Burnor