Tools & Skills

Tools are functions the agent calls on its own during a response - reading a file, running a shell command, doing a web search. You see each tool call as a card in the message stream showing what ran and what came back. In Ask mode, every tool call pauses for your approval before executing - unless you turn on auto-approve read-only tools (Settings → Agent, beta.28, off by default), which lets pure reads (search, grep, glob, symbol lookup, Map/memory/knowledge/session queries) skip the prompt while writes, web, and shell still ask. Shell can never auto-approve in Ask mode.

Skills (/commit, /debug, etc.) are structured workflows you trigger explicitly. They load a pre-written policy into the agent's context that shapes how it approaches the task - which tools it's allowed to use, what order to do things in, and when to stop and ask you. You invoke them with a slash command in any AI panel.

Client-side slash commands (/help, /clear, /compact, /mode, /preview, /map, /export) are handled entirely in the app - nothing goes to the LLM.

The shell tool runs commands in your project directory: git operations, package managers, test runners, compilers, linters - anything you'd run in a terminal. On Windows the shell tool runs commands through cmd.exe, not PowerShell and not bash, and this is separate from the Terminal panel, which prefers PowerShell 7. PowerShell-only syntax ($env:X, cmdlets) and bash-isms (mkdir -p, export, $(...)) do not work; use the file_system tool for files and folders.

Every command is classified into one of three tiers before it runs:

• SAFE (auto-approve in Act mode): ls, cat, git status, and similar read-only commands.
• MODERATE (brief confirmation): npm install, git commit, and similar.
• DANGEROUS (full approval dialog): rm, chmod, git push, curl, and similar.

In Ask mode, shell commands always show an approval card regardless of tier - there is no auto-approve timeout.

After every execution, output is scanned for 13 credential patterns: SSH private keys, AWS AKIA* keys, GitHub ghp_* PATs, OpenAI sk-* keys, JWTs, and high-entropy strings over 40 chars (scored by actual Shannon entropy, so DNA sequences, hex digests, and UUIDs are not redacted).

Air-gap mode blocks all network-touching shell commands: curl, wget, ssh, git clone/push/pull, npm install, pip install, docker pull.

Both web tools are blocked entirely in air-gap mode.

Two non-core tools let the agent reach outside its own single-model turn for a hard subproblem. Both are off by default and only visible when their setting is enabled.

When deferred tool loading (agent.deferred_tools, off by default - see the KV-cache section in this page's overview) is turned on, the model's native tool list shrinks to a small core set for KV-cache efficiency, and everything else pages in through two meta-tools instead of being listed up front:

Both are always part of the core set (so their own schemas never move), but they only matter when deferred tool loading is on - with it off, every registered tool (including consult_mixture and spawn_agent when their own settings are enabled) is listed natively as usual and these two meta-tools go unused.

open_preview is the simple way to open the Preview tab. With no arguments it auto-detects a running dev server (Vite/Next/CRA/Astro/…) on the common localhost ports and opens the panel to it. If nothing is running but the project has an index.html, it serves that folder locally instead, so plain HTML/JS sites and no-build-step projects are previewable too. Pass url to target a specific localhost address. It only opens the panel - the tool never starts a dev server for you (that's still the shell tool's job; you can also start one yourself with the one-click Start button on the Preview empty state, which runs your project's dev script in a Terminal tab).

preview_interaction lets the agent drive the Preview tab (an embedded browser) once it's open. Actions:

• screenshot - captures a PNG and returns an img_XXXXXXXX handle
• navigate - loads a URL. Localhost/loopback always works; a non-localhost origin requires your prior approval and is refused entirely under Air-Gap mode
• click - clicks an element by CSS selector (approval-gated by default)
• type - sets an input/textarea value (no simulated keystrokes) so the agent can fill in a search box, a login form, or any other field. Password and other credential fields are always refused outright - never approvable, never a silent no-op - and every other value is scanned for credential signatures before you're asked to approve it. Every type shows you the exact field and value and asks every time; nothing is remembered site-to-site the way navigate/click approval is.
• submit - submits a form. Asks for your approval on every call, even on an already-approved site, and shows the real field values read from the page rather than what the agent claims it's sending. Clicking a form's submit button after the agent has typed into that form goes through this same real-values approval, not the lighter click approval.
• getDom - returns outerHTML for a selector (output capped at 8,000 chars)
• getConsoleErrors - returns sanitized JS console errors

preview_script runs several of those actions in one call - up to 8 steps drawn from navigate, click, getDom and screenshot - so the agent stops spending a whole turn per click while it is finding the right page. It is not a shortcut around anything: each step is executed exactly as if the agent had called preview_interaction for it, so every approval prompt, air-gap refusal and credential scan happens the same way and at the same moment. Two behaviours worth knowing: type and submit can never be part of a batch (if a script asks for one, it stops there and the agent has to request that action on its own, so you always approve typing and submitting against the page as it stands right now), and if any step does not do what it claimed - a selector matched nothing, a site was refused - the rest of the script is abandoned and the agent is told which step failed rather than carrying on against a page it never reached.

vision_query takes an image_id from a prior screenshot and a plain-English question (max 500 chars), sends both to your configured Vision Language Model, and returns a text answer. This is how a text-only loop driver (e.g., Claude) can "see" the screen.

To use vision features: configure a VLM in Settings → Models → Vision Model, and have the Preview tab open with a dev server running.

By default, every widened-browsing session is ephemeral - its cookies and storage are wiped when the browser surface tears down, so the agent is never logged in anywhere across sessions. That stays true unless you deliberately change it.

"Keep the agent signed in" (Settings → Safety) is available, and off until you turn it on. Switching it on asks you to confirm first, because it is a real grant of authority: on a site you approve, the agent acts as you until you revoke it. If you had this setting on in an earlier build it has been reset to off - the earlier switch approved a version of the feature that was never actually wired, so the app asks again rather than assuming the old answer still applies.

With it on, each site you grant gets its own cookie jar, kept separate from every other granted site and from the rest of the app. The grant is per site, requested the first time the agent navigates there, and it covers that site's subdomains.

You stay in control of it: Settings lists every persisted site and lets you revoke one or all of them, a site you decline is remembered so you aren't asked repeatedly (with an Ask again action if you change your mind), and turning on Air-Gap mode wipes every persisted login outright, naming the affected sites before it clears them.

One honest caveat while this is new: signing in to a site that authenticates by redirecting through a third party (a "Sign in with…" flow) will not work - the browser blocks cross-site redirects on purpose, and that restriction is not something to work around.

This isn't a tool the agent calls - it's built into the normal file-read path. When the agent (or you, via an attachment) opens a PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, EPUB, or RTF file, Bodega converts it to Markdown automatically before the content reaches the model. Legacy binary Office formats (.doc, .ppt, .xls) are also supported - .doc conversion is verified against a real fixture, .ppt/.xls use the same underlying parser and are extrapolated from that.

Two entry points, same converter:

• The agent reads the file directly with file_system - the binary-format detector routes it to the converter instead of returning garbled bytes.
• You attach the file in the chat composer - the same converter runs before the content is added to your message.

What it won't do:

• Scanned PDFs are refused. If a PDF's extracted text is near-empty relative to its file size, Bodega assumes it's an image scan and tells you so rather than returning blank content - it does not perform OCR.
• Encrypted/password-protected documents are refused with a clear message.
• 100MB input limit. Anything larger is refused before conversion is attempted.
• 50,000-character output cap on the converted Markdown, with a truncated marker appended when a document is cut off.

Why it's safe on untrusted files: the actual conversion runs in an isolated child process, not in Bodega's main backend. A malformed or hostile document that crashes the parser takes down that one child process - you get a "could not convert this document" refusal, not a backend crash.

The learn_skill tool turns "I keep doing this same workflow" into a reusable skill. Point it at a source - a folder inside your workspace, or a URL - and it has the model draft a spec-conformant skill YAML, validates the draft, and returns it as a preview for you to review.

This first version stops at the preview: it reads, drafts, and validates, but it does not write the skill or change your skill registry yet - the save/approve/reload steps come later. So you can use it today to see exactly what a skill for a given source would look like before anything is committed.

What it needs:

• source - directory (a path inside the workspace) or url.
• path_or_url - the folder path or the http(s) URL to learn from.
• skill_name - lowercase letters, numbers, hyphens, or underscores.
• skill_description - a one-line summary of what the skill does and when to use it.
• triggers (optional) - comma-separated trigger phrases; defaults to /<skill_name>.

Safety: directory sources go through the workspace sandbox (no escaping your project), URL sources go through the SSRF-protected fetcher, and the source is truncated before authoring. Under air-gap, URL sources are refused with a clear message - directory sources still work. If the model produces invalid YAML, you get an error rather than a malformed skill.

Skills load a policy into the agent that controls how it approaches the task. Type / in any AI panel to see autocomplete. Twelve ship built in:

Skills are not mode-restricted. There is no per-skill "Code Mode only" flag. What is gated is automatic activation: Bodega only matches a skill from your phrasing when you are in Code mode and skills.auto_activation is on. An explicit /trigger works in any panel, in either mode. A skill can still fail for a mundane reason - /commit needs the shell tool, and shell is not available everywhere.

Skills load from three places, and only one of them is gated:

A skill that arrives inside a repo you cloned does not run. It is skipped before its frontmatter is parsed - never registered, never listed to the model, never executed - until you approve it.

Approval is keyed to the SHA-256 of the whole SKILL.md file, frontmatter and body together, paired with that project's resolved path. Two consequences worth knowing:

• Editing an approved skill re-prompts. Any byte change is a new hash. This is deliberate: the body is injected into the agent as instructions, so changing it is as much a change of behaviour as changing the policy fields.
• Approval does not travel. The same skill in a second checkout of the same repo is a separate decision.

Approve at Settings → Skills → Project Skills - the block appears only when the open project actually has skills pending - or from the small approval chip in the corner when you open a project. From a shell, bodega skills trust lists them and bodega skills approve <name> approves one, printing the content hash it approved. There is no "deny" verb; declining is simply never approving. An approval you regret can be revoked: click the Approved label in Settings → Skills → Project Skills and the skill goes back to requiring approval.

The trust record lives in skill-trust.json in your Bodega data directory and fails closed: if that file is missing, corrupt, or unreadable, every project skill is refused rather than allowed. Each record also notes what was approved, when, and from which surface (Settings, CLI, or API). One hard refusal: a .bodega/skills/ entry that is a symlink or junction pointing elsewhere is never loaded and cannot be approved - it shows as Blocked (link) in Settings.

Bodega One Code (the CLI) sees exactly the same skills the app does - it starts the same backend and reads the same registry, and it ships no skill set of its own.

• bodega skills / bodega skills list - what's loaded
• bodega skills trust [--json] - project skills and their approval state
• bodega skills approve <name> - approve one

One difference worth knowing: the backend's skill listing does not distinguish a skill you wrote from one the project shipped. The CLI works that out itself by checking whether the file exists under the project's .bodega/skills/, and tags it project ⚠ [untrusted] when it isn't approved. The app's Settings list does not make that distinction the same way, so the CLI is the better place to audit what a repo is trying to hand your agent.

These are handled entirely in the app - nothing goes to the LLM.

Custom agents let you define named profiles with a tailored system prompt, an optional pinned model, a tool allowlist, and an iteration cap.

To create a custom agent:

1. Go to Settings → Custom Agents
2. Fill in: Name (required, max 100 chars), System Prompt (required, max 6,000 chars), and optionally Description, a pinned Model, Tool Allowlist, Read-only filesystem, and Max Iterations (1–50)
3. Leave the tool allowlist empty to allow all tools. Add specific tools to restrict what the agent can call.
4. Save.

To use a custom agent:

1. Open Code Mode and find the Agent panel
2. In the Agent panel header, click the profile picker dropdown (robot icon, shows "Default" when none selected). The picker is hidden if you have no custom agents.
3. Select a custom agent. The next message you send applies that profile.
4. Switch back to Default to remove the profile.

If a selected agent is deleted, the picker falls back to Default automatically. Tool allowlists are validated against the live tool registry - invalid tool names are rejected at create time.

Permission mode (ask/plan/act) and sandbox rules are global settings, not agent-derived.

The ACP (Agent Client Protocol) server lets external coding agents run as Fleet members inside Bodega. Supported agents: Gemini CLI, Claude Code, Codex, and Cursor.

Configure at Settings → ACP Agents. What each one needs:

• Gemini CLI - GEMINI_API_KEY and @google/gemini-cli installed globally
• Claude Code - ANTHROPIC_API_KEY and @zed-industries/claude-code-acp installed
• Codex - OPENAI_API_KEY and @zed-industries/codex-acp installed
• Cursor - cursor-agent CLI installed and cursor-agent login run once (subscription auth, no API key)

Once configured, ACP agents appear as Fleet session options. Communication is NDJSON-RPC over stdin/stdout - Bodega spawns the agent as a child process and routes prompts through the ACP session protocol.

What ACP agents can and can't do:

• File system and shell access routes through Bodega's own tools - sandbox and air-gap rules still apply
• ACP agents do not go through QEL verification - they show an "external - not QEL-verified" badge
• Blocked entirely in air-gap mode - enabling air-gap kills any running ACP subprocesses

When using llama.cpp as your embeddings provider, Bodega can manage the embedding server process automatically - separate from the chat server (port 8080), running on port 8081 by default.

To set it up:

1. Install an embedding-capable GGUF first: go to Models → llama.cpp → Discover and download a model such as nomic-embed-text or a bge model
2. Go to Settings → Knowledge → Search & Embeddings (or Settings → Models → Codebase Embeddings)
3. Set provider to llama.cpp
4. Enable the "Let Bodega manage the embedding server" toggle
5. In the GGUF dropdown, select an installed model (the dropdown only shows models from your llama.cpp library)
6. Optionally set a custom port (default: 8081)

The embedding server starts with the --embedding flag and is fully independent of the chat server. If you'd rather manage the process yourself, leave the toggle off and type the path manually.

The Review button in the Git panel runs an AI code review against your current git diff - the "review before I commit" case. It uses your configured LLM provider, so it works fully locally.

To use it:

1. Make changes to your project files (staged, unstaged, or both)
2. Open the Git panel in Code Mode (Activity Bar → git icon)
3. Click Review (next to the Generate commit message button)
4. The review result appears inline as a markdown block in the Git panel

If the working tree is clean, the review falls back to comparing the branch against its base (the PR-scope view). Large diffs are clipped and a truncation note is appended.

Delta-only re-review (beta.28): files unchanged since your last review of the project are skipped - the result notes how many, with a Review everything link for a full pass.

This is separate from the /review skill. The /review skill reads source files and runs a code quality analysis. The Git panel Review button reads the git diff and focuses on what changed.