Usage¶

This guide shows how to use Booley day to day. You don't need any experience with AI coding agents to follow it.

Contents

1. Read this first
2. Check your setup
3. Choose how to work
4. Interactive Mode: first session, good prompts, reviewing changes, editing instructions, waveforms
5. Entering the Sandbox without VS Code
6. Auth & billing
7. Reporting problems and feedback

Goal Mode has its own guide, GOAL-MODE.md. Every command, Flow, and Specialist is listed in CLI-REFERENCE.md.

Read this first¶

This guide picks up after installation and project setup. It assumes that booley init and the booley-setup skill have both finished. If they haven't, install Booley using the README, then follow SETUP.md.

What Booley does. Booley lets a Developer Agent, such as Claude Code or Codex, run your project's EDA tools. The Developer Agent is more than a chatbot: it can read and edit files, run commands, and call Booley while it works. You describe what you want in plain language, and the Developer Agent picks the right Booley Flow or Specialist and runs it. You are still responsible for reviewing its reasoning, its code, and the hardware results.

Booley offers two kinds of capability:

• Flows (sim, lint, synth, fpga) run EDA tools in a fixed, predictable way. No AI is involved.
• Specialists (reviewer, mutation_tester, coverage_analyst) are small LLM-powered capabilities that each do one focused job.

For direct CLI reproduction, see live Flow progress and logs, including quiet and verbose output.

Both run inside the Sandbox, a Docker container that holds the EDA tools and keeps the Developer Agent away from the rest of your computer.

Sandbox limits and network egress for both execution modes are host-owned [sandbox] settings; see Host configuration.

Where you type. This guide uses three places:

Command blocks go in the terminal named in the text around them. Sentences in italics are prompts for the Developer Agent chat. Skills such as /booley-goal also go in the Developer Agent chat, not in a terminal.

Booley uses some terms with exact meanings. When one is unfamiliar, look it up in the glossary linked from the context map.

Selecting a Project¶

Use -C/--project PATH on Project-bound commands to select a checkout or worktree, including a nested directory in it. Paths are relative to the caller; Booley does not change the process directory. With no selector, cwd discovery stays unchanged. An explicit canonical selector overrides RTL_PROJECT_ROOT.

booley -C ../other targets
booley session -C ../other status
booley session status --project ../other
booley flow lint --target lint --project ../other

Use the selector once, at the root, command, or nested operation. It also works on chat, doctor, init, upgrade, cleanup, and feedback, and on bare booley inside the Sandbox to select the Project for chat. On the host, bare booley prints help without resolving the selector. auth --status optionally uses the selected Project and its auth policy; outside a Project it reports both supported AI agent clients (Claude Code and Codex), unless --app selects one. Bare cheat and cheat --list accept and ignore the selector without discovering a Project. bootstrap, projects, and eda retain their grammar and do not accept the new selector. Full option names are stable; ambiguous abbreviations produce an error. Arguments after a command's payload -- stay opaque.

Selection chooses the checkout, while BOOLEY_DIR chooses the Booley Directory; an external data override remains supported. Checkout-local data configuration and initialization's destination scope keep their existing precedence. A selector requires an existing directory; init accepts an uninitialized directory.

cheat --project-files selects the Project Files section.

Flows and Specialists accept --timeout DURATION: positive integer seconds (90 or 90s), minutes (30m), hours (2h), or descending combinations (1h30m). MCP parameters and config keys use milliseconds.

First, verify your setup¶

Run these in a host terminal. They check that Booley works and show what it can see:

booley doctor          # health check: configuration, Sandbox Image, EDA tools
booley targets         # every Target Booley can see, grouped by core
booley cheat           # available quick-reference sections

Don't continue until booley doctor shows no failures or warnings.

• If booley is not found, go back to the installation instructions.
• If Booley says its version changed, type /booley-heal in the Developer Agent chat.
• For a quick overview of Booley, start with booley cheat. It lists the available sections; print the ones you need, for example booley cheat --goals or booley cheat --commands --project-files. Use booley cheat --all for the whole cheatsheet; booley cheat --list also shows the section list.
• booley doctor --deep goes further and runs short real simulations, lints, and syntheses.

Upgrade review¶

When Doctor reports upgrade.review-pending, run booley upgrade status --json and invoke /booley-heal to review the release changes. Follow the Doctor upgrade-review workflow for plain, deep, and host verification, acknowledgment, and the final plain check.

Choose how to work¶

Start with Interactive Mode to explore and run individual Flows. Use /booley-goal in the same Developer Agent chat when a task needs mandatory completion conditions. Goal Mode supports both human guidance and unattended work, with one linked worktree and Goal Branch per session; see GOAL-MODE.md.

Interactive Mode¶

Open your first Developer Agent session¶

1. In a host terminal, go to your RTL project and open VS Code:

   cd path/to/your-rtl-project
   code .
   

   If code is not found, open VS Code yourself and use File → Open Folder.

2. When VS Code offers Reopen in Container, accept it. If the offer doesn't appear, open the Command Palette (Ctrl+Shift+P) and run Dev Containers: Reopen in Container. The first start can take several minutes. When it's done, the lower-left corner of the window says you are in a Dev Container.

3. Open Terminal → New Terminal. This is a container terminal. Start the Developer Agent:

   booley
   

   booley (or booley chat) just starts the Developer Agent chosen in [agent].provider in .booley/booley.toml:

   Provider	Same as running
   claude	claude (Claude Code)
   codex	codex (Codex CLI)

   From then on you are using that CLI's own chat. To pass it extra options, run claude or codex directly. To run several sessions, open more container terminals.

   Prefer a chat panel? The Claude Code or Codex VS Code extension is already installed in the container. Open its panel instead of using the terminal.

   If you see a login screen instead of a chat, run booley auth --status in a host terminal and follow its advice (usually booley auth). Then run Dev Containers: Rebuild Container and try again. See Auth & billing.

4. Type this safe first request into the chat:

   Check whether Booley Interactive Mode is ready. List the available simulation targets and explain what each one is for. Do not change files.

   The agent asks Booley for this and summarizes what it found. You never call Booley's MCP tools yourself.

5. If the agent listed a simulation Target, try a real run:

   Run the tests on the most appropriate simulation target. Do not edit any files. Tell me what ran, whether it passed, and where the detailed report was written.

   A good answer names the Target and Flow it used, says whether the result was a pass, a design failure, or an infrastructure failure, and suggests what to do next. If there is no simulation Target, ask for lint instead.

That's a complete session. You don't need to read the rest of this guide before you keep going. Just ask for what you want:

• "Debug the backpressure test failure on the sim_heavy target."
• "Compare synth area between the following commits ..."
• "Run a security review on the control unit module."

You don't need to know Flow names, flags, or where reports go. Give the agent the goal and any limits, and it works out the details.

Write a useful prompt¶

Brief the Developer Agent the way you would brief an engineer joining the task:

• what you want to learn or change,
• the Target or module, if you know it,
• any limits,
• what evidence you want to see.

If you only want an investigation, say do not edit files. For example:

The ready signal sometimes remains low after reset on the sim_full Target. Reproduce the failure, inspect the waveform, and explain the likely cause. Do not edit files yet. Show me the evidence and propose a fix.

If the agent heads the wrong way, don't start over. Tell it which assumption was wrong or what evidence you want next.

What the Developer Agent is allowed to do¶

Inside the container, the Developer Agent never asks for permission before acting. That is deliberate: the container itself is the safety boundary. It can only see your project, and its only network access is to the AI provider. Booley does not change your Claude Code or Codex settings outside the container.

Always review changes yourself. Use git diff in a container terminal and run the relevant checks. Asking the agent to explain its diff helps, but it doesn't replace your own review.

Tip: let the Developer Agent commit; you push. Let the Developer Agent commit its own work; it writes good commit messages. It can't push to GitHub or any other server, because the container blocks that network access. So: let it commit, review the commits, then push them yourself from a terminal outside the container.

Per-session logs of Flow and Specialist calls through Booley’s tool server are saved in .booley/.interactive_logs/. Chat transcripts live in the Developer Agent CLI’s own session storage. If the Developer Agent can't reach Booley (booley is missing from its /mcp list), see TROUBLESHOOTING.md. How the connection works is in ARCHITECTURE.md.

Editing Project instructions¶

Root AGENTS.md and CLAUDE.md normally link to the canonical Booley Directory guide. Editing either link edits that guide. In an embedded non-Stealth layout, stage the canonical file with git add .booley/AGENTS.md, substituting your configured Booley Directory if different. The root links remain ignored. For a separate Booley repository, including Stealth, stage and commit AGENTS.md inside that repository. An explicitly selected hybrid footprint instead uses a matching tracked root AGENTS.md copy; keep it identical to the canonical guide and stage changes to both copies.

Viewing waveforms¶

When a simulation with tracing fails, the Developer Agent reads the waveform on its own with bwave. When you want to see it, ask: "show me the FIFO handshake around the failure". The agent opens it in a VaporView tab in VS Code, showing just the signals and time range that matter. VS Code installs the extension automatically when you attach to the container. If it is missing, see TROUBLESHOOTING.md.

You can also open a view yourself:

bwave gui                                                      # the latest trace
bwave gui @dut --signals 'tb.clk%b@red' \
  --group 'FIFO handshake=tb.dut.fifo.*%h@green' \
  --group 'Control=tb.dut.ctrl.state%h@blue' --time 1200c:1400c

The clock always goes on the first row. Each --group 'NAME=PATTERN' becomes a named, collapsible section. --time START:END puts markers at both ends so the status bar shows the span. Add %b/%h/%d to a signal for binary, hex, or decimal, and @red/@blue/@green for a color. bwave gui --help has the rest. If a view fails to open, see TROUBLESHOOTING.md.

Entering the Sandbox without VS Code¶

Reopen in Container needs VS Code. Without it (in CI or for unattended work), booley session starts the same container. Run these on the host, after booley init:

booley session up                       # create or start the container
booley session enter                    # open a shell inside it
booley session enter -- booley doctor   # or run one command and exit
booley session status                   # running (with VS Code owner/name) | stopped | absent
booley session refresh                  # rebuild the image and recreate the container
booley session down                     # stop and remove a headless Sandbox

booley session enter works like a container terminal, so every container-only command works through it. Ctrl-C on a command run with -- stops everything it started inside the container.

session refresh is safe to interrupt; the prior container stays usable until the new one is ready. It won't replace a container that VS Code opened; use Dev Containers: Rebuild Container for that. If your EDA tools need a license server, run booley session down before refreshing.

up and enter reuse the current Sandbox, including one owned by VS Code. status identifies a running VS Code Sandbox by owner and name. CLI down and up --rebuild refuse editor ownership: close the window or stop it through Dev Containers, and use Dev Containers: Rebuild Container to rebuild it.

Auth & billing¶

The Developer Agent and Specialists use the provider set in [agent] provider in booley.toml: claude (the default) or codex. Each one signs in the same way its own app does, with either a subscription or an API key:

Both work in Interactive Mode and Goal Mode.

• Subscription: usage counts against your plan. Claude rate-limit events make Booley wait and retry a Specialist call within its retry and timeout budgets. Codex usage caps stop the call; it must be invoked again after the limit resets. Resume an interrupted Goal session with goal_status(rules=true).

• API key: you pay per token.

If an API key is exported, it is used even when you also have a subscription. To choose explicitly, set [agent] auth = "subscription" or "api_key"; see CONFIG.md. booley auth --status shows which login is in use.

For long runs, run booley auth. The normal login renews itself periodically, and a renewal can sign out every running Developer Agent or Specialist in the middle of a run (details). booley auth saves a login that doesn't need renewing:

Codex has no long-lived subscription token, so for Codex this means paying per token instead of using your subscription.

The saved login lives in ~/.config/booley/, outside every project, so it can't be committed by accident. Booley passes it to every container on its own, including VS Code's; rebuild an existing container once to pick it up.

booley init --skip-credentials skips the login check, for CI machines that have no login on purpose. Don't use it for normal setup.

When Booley itself misbehaves¶

Maybe a Flow failed with no useful message, a doc describes a setting that doesn't exist, or a message looks like a crash when nothing crashed. Type /booley-feedback in the Developer Agent chat while the problem is still on screen. It records how to reproduce it, checks Booley's own code before blaming it, removes your project's names, and saves a report file for you to read and share yourself. Booley never sends it anywhere.

It doesn't have to be a bug. Confusing behavior, praise, complaints, wishes, or "this wasn't worth the setup cost" are all worth one sentence to /booley-feedback. See CONFIG.md.

In the Sandbox, each Project has one Findings Log shared by all of its worktrees. The log and default local report stay in the Main Booley Directory, even when a worktree has its own Paired Checkout. When the skill uses the feedback CLI, its -C / --project option selects the checkout used for context; it does not move that shared log or the default report. For Projects, the BOOLEY_DIR environment variable selects shared storage. Outside the Sandbox, without that override, storage is discovered from the selected checkout and may use a separate log. Use the report paths provided by the skill.

Source: docs/user/USAGE.md on GitHub