CodeBuddy Code native reference
Start with the CodeBuddy Code setup.
Import an existing setup
agnostic-ai import codebuddy
agnostic-ai sync --plan
agnostic-ai sync
agnostic-ai sync --check
agnostic-ai lint
Import reads root and scoped instructions, modular rules, agents, skill folders and resources, commands, settings, command and prompt hooks, and root MCP files.
- Native fields with no portable equivalent stay under
x-codebuddy. - Top-level environment and credential settings stay in the native file.
- Import rejects nested credentials and literal credentials in inline agent MCP servers. The error names the field, not the value. Use native environment references in supported MCP fields.
- Native MCP import reads
.mcp.jsonbefore deprecatedmcp.json. - Configure the MCP opt-in before syncing imported project servers.
Instruction frontmatter:
- Keeps native
enabled,alwaysApply, andpathsvalues. enabled: false, andalwaysApply: falsewithout paths, stay inactive.- The source-only hint
x-codebuddy.instruction-file(CODEBUDDY.mdor.codebuddy/CODEBUDDY.md), with a validatedscope, restores the original location. It is left out of native output. - If both root alternatives exist, pick one with the entry-point file configuration before import.
Sync reports a conflict before writing when a controlled root file shares its instruction policy with effective shared or local instructions, root rules, or the target overview. Scoped native files also reject mixed activation policies for one path.
Enable project MCP output
outputs:
codebuddy:
root-mcp-file: .mcp.json
- Sync writes an explicit
type:stdio,http, orsse. - Import accepts native JSONC and infers an omitted or empty type from
command(stdio) orurl(http). - Stdio servers keep
command,args,env, andcwd. Remote servers keepurlandheaders. Both keepdescription. - Native
cwdstrings stay unchanged. CodeBuddy expands uppercase${NAME}and${NAME:-default}there. Sync does not expand environment references. x-codebuddy.defer_loadingandx-codebuddy.toolskeep native loading controls.- Sync rejects disabled servers and remote-server
cwd. - Sync never approves project servers. CodeBuddy asks the user before the first connection.
At user scope, sync and import use the first existing file:
~/.codebuddy/.mcp.json- deprecated
~/.codebuddy/mcp.json - legacy
~/.codebuddy.json
New output uses the preferred file. Comments, account state, the global projects map, and unmanaged servers stay intact.
Fields and limits
Agents
- Names use lowercase letters and hyphens.
- Sync rejects scoped shell and file tool patterns. Keep those policies in permission rules.
- When an agent needs a policy CodeBuddy cannot represent, use per-spec target filters.
x-codebuddy.toolsgives an explicit native exposure list. - Accepted fields:
name,description,tools,disallowedTools,model,effort,skills,mcpServers,permissionMode,maxTurns,background,initialPrompt,memory,hooks,disable-model-invocation(keeps a manual-only agent out of model selection). - Native additions go under
x-codebuddy. - Portable tool names map only to verified native tools. Sync fails when a restriction has no mapping, so access never widens.
- Native agent memory adds
Read,Write, andEditeven to a restrictive tools list, includingx-codebuddy.tools: []. Sync reports this throughon-unsupported;errorrejects it before writing.
Sub-agent MCP tools (CodeBuddy 2.181.0 or later, docs):
mcp__docsormcp__docs__*exposes one named server.mcp__docs__searchexposes one tool.- Portable
can: [mcp:docs]writesmcp__docs. These forms exclude other servers. - The global wildcard
mcp__*is unsupported in an agent allow list. - Do not use
--agentto isolate a main session's MCP tools. CodeBuddy 2.181.0 still exposed other configured servers.
Empty tool lists:
- A portable empty
toolsorcanlist fails sync, because CodeBuddy before 2.179.0 gives such an agent every tool. - For no tools, set
x-codebuddy.tools: []. Sync writestools: []and notes that only CodeBuddy 2.179.0 or later reads it as no tools. - CodeBuddy still adds its messaging tools and the plan-exit tool to such an agent.
- Import keeps a native
tools: []asx-codebuddy.tools: [].
Skills and commands
- Skills keep native scoped allowed-tool strings such as
Bash(git:*)andEdit(src/**/*.ts), invocation controls, and nativecontext,agent,model, andhooks. - CodeBuddy applies agent, model, and hook overrides only with
context: fork. - Bundled files are copied unchanged.
- Commands keep description, argument hint, model, allowed tools, invocation control, and body placeholders.
- Global commands are not managed by agnostic-ai, although CodeBuddy has a user command directory.
MCP permission rules
- Accepted:
mcp__server,mcp__server__*, and exactmcp__server__tool. - The all-server
mcp__*form works inaskanddenyonly. - Partial-segment wildcards are rejected.
- These follow the native permission grammar.
Settings
modelmaps tomodel.effortmaps toreasoningEffortand acceptsminimal,low,medium,high,xhigh,max.- Permission lists map to
permissions.allow/ask/deny.permissions.default-modemaps topermissions.defaultMode. - Session retention maps to
cleanupPeriodDaysat user scope. - Voice has no documented native key.
- Project
autoModeandpermissions.defaultMode: autoare rejected, because CodeBuddy ignores them there. - With no
permissions.default-modein a home settings spec,approvalsset toreviewfor CodeBuddy makessync --globalwritepermissions.defaultMode: "auto"to~/.codebuddy/settings.json. See review through the tool's own reviewer.
Hooks
- Command hooks keep native event names, matchers, and timeouts in seconds. Arguments are shell-quoted into the command.
- Prompt hooks (
type: prompt) work onStop,UserPromptSubmit, andPreToolUsein project settings. They writeprompt,timeout, andcontinueOnBlock. - CodeBuddy has no prompt
modelfield, so sync drops it with a note. - Sync rejects prompt hooks on other events, prompt hooks in user settings, and other handler types.
- Settings merge with existing native keys and hook entries.
- CodeBuddy reviews hook changes itself. Frontmatter hooks also need the user's
allowUntrustedFrontmatterHookschoice. Sync never makes trust or approval decisions.
Not generated
Ignore files, review configuration, environments, plugins, credentials, sessions, and automatic memories have no output in this adapter.
Config keys
Shared root instruction file: entry-point files.
| Output key | Default |
|---|---|
dir under outputs.codebuddy | .codebuddy |
outputs.codebuddy.rules-dir | .codebuddy/rules |
outputs.codebuddy.agents-dir | .codebuddy/agents |
outputs.codebuddy.skills-dir | .codebuddy/skills |
outputs.codebuddy.commands-dir | .codebuddy/commands |
outputs.codebuddy.conf-file | .codebuddy/settings.json |
outputs.codebuddy.root-mcp-file | Unset |
dir moves the tool directory; individual keys win. Scoped instruction files keep their native names. Custom paths outside CodeBuddy's documented paths need its own discovery configuration.