CodeBuddy

Vendor: Tencent Install name: codebuddy Status: GA Native config: <project>/.codebuddy/rules/apothem-rules.md

InstallationCopy Anchor Link

apothem install --harness codebuddy --project /path/to/project

The adapter writes one project-scope rules file from the shared Apothem rules and governance surface, Apothem's helpers as CodeBuddy subagents in the project (see Subagents), and two hooks (see Hooks).

It also writes Apothem's skills, and the rules and templates they cite, to your user home, before it touches the project (see Files outside the project).

Files written:

• <project>/.codebuddy/rules/apothem-rules.md, the rules file.
• <project>/.codebuddy/agents/<name>.md for each Apothem helper, in the project.
• <project>/.codebuddy/settings.local.json, the hook registration, in the project. Your own entries in it stay.
• <project>/.apothem/support/hooks/, the hook scripts, in the project.
• ~/.codebuddy/skills/<name>/SKILL.md for each Apothem skill and command, in your user home.
• ~/.config/apothem/rules/ and ~/.config/apothem/templates/, in your user home.

Files outside the projectCopy Anchor Link

The install also writes Apothem's skills to your user home, before it changes anything in the project:

These folders are shared. They are not private to the project:

• Every project you install codebuddy into uses the same copy of ~/.codebuddy/skills/, and the install writes the same files into it each time. CodeBuddy is the only tool that reads that folder. The rules and templates under ~/.config/apothem/ are written by the other tools' installs as well, with the same files.
• --project chooses the rules file to write and which project the install belongs to. It does not change where the skills go.
• The install adds no skill or rule file to your repository. The project gets the rules file, the subagent files in .codebuddy/agents/, the hook registration in .codebuddy/settings.local.json, plus the .apothem/ folder every project install creates, which also holds the hook scripts.
• The home folders are written first. If that fails, for example because a folder in the path is a link that leaves your home directory (a link that stays inside it is followed) or cannot be written, the install stops with the error before anything in the project changes.
• A skill folder with an Apothem skill's name that Apothem did not write is left alone, and the install prints a warning that names it. Rename or move it, then run apothem update. apothem verify fails while that name is held.
• The files add up to a few megabytes.

The install prints a note that names the folders it writes outside --project, and --dry-run lists them.

SubagentsCopy Anchor Link

CodeBuddy reads a subagent from a Markdown file in <project>/.codebuddy/agents/ (project agents) or ~/.codebuddy/agents/ (user agents), per the CodeBuddy sub-agents documentation. The install writes one file per Apothem helper into the project folder only, and writes nothing to ~/.codebuddy/agents/.

Each file keeps the helper's instructions unchanged and carries these frontmatter keys:

Only the tool names CodeBuddy's documentation shows are written. Its Settings page lists the tools, and its sub-agents page names one more tool, which the list below includes:

Read, Grep, Glob, Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch,
Agent, Task, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate,
AskUserQuestion, ExitPlanMode, LSP, Skill, SlashCommand

A tool the source names that is not in that list (for example PowerShell or TodoWrite) is left out of both fields. A tool with a pattern, such as Bash(rm *), has no form in a comma list: as an allowed tool it is left out, and as a denied tool it denies the whole tool. A helper that cannot edit files keeps that limit: it lists no Write or Edit among its tools and denies both. The install writes no model key, so a helper runs on the model CodeBuddy selects, and no permissionMode or hooks key.

Things to know:

• The subagent files are ordinary project files. Commit them with the project or list .codebuddy/agents/ in .gitignore; Apothem does not choose for you.
• CodeBuddy loads subagent files added by hand at the start of the next session, so start a new session after the install.
• A file of yours with an Apothem helper's name is saved under ~/.apothem/backups/ and then replaced. The uninstall does not put it back. Files with other names are never touched.
• CodeBuddy's IDE Subagents page shows keys the CLI page does not list, and Apothem has not confirmed that the IDE accepts disallowedTools or maxTurns.

HooksCopy Anchor Link

CodeBuddy runs hooks from the hooks key of its settings files, per the CodeBuddy hooks documentation, which marks hooks as Beta. The install registers two:

Both add context for the model. Neither blocks a tool call or a session.

Apothem registers no PreToolUse guard on CodeBuddy. CodeBuddy's documentation lists additionalContext (the field Apothem's guards speak through) for SessionStart, UserPromptSubmit and PostToolUse, and lists only permission and input fields for PreToolUse. A guard registered there would cost a process start on every tool call and might deliver nothing, so the write, edit and shell guards, the AskUserQuestion check and the session-end protocol stay on the tools that deliver them. Apothem will register a guard on a CodeBuddy event once the documentation, or a probe, shows that it reaches the model.

Where the files go

Each registered command names the interpreter Apothem found when it ran, and the absolute path of the project, so it is machine-specific. That is why the install writes the local file and never the committed <project>/.codebuddy/settings.json. The install does not edit .gitignore: check that yours lists .codebuddy/settings.local.json and .apothem/, so a teammate's checkout does not receive commands that point at your machine.

Paths the shell would misread. A project or interpreter path that contains $, a backtick, a double quote or a backslash is refused before anything is written: inside the quoted command it would run a different file, or break the JSON the command is written into. The error names the path; move or rename the project and run the install again. A space or an apostrophe in a path is fine.

A command looks like this, with your interpreter and project path in place of the two paths:

"/path/to/python" "/path/to/project/.apothem/support/hooks/dispatch.py" --contract codebuddy SessionStart

--contract codebuddy is a no-op for the output: CodeBuddy reads the same envelope Claude Code does. CodeBuddy runs hook commands through your shell, and through Git Bash on Windows (it supports neither cmd.exe nor PowerShell), so the commands use bash quoting and a forward-slash interpreter path. Install Git for Windows if CodeBuddy asks for it.

Review the hooks once the install has run. CodeBuddy takes a snapshot of its settings at startup, does not hot-load a settings file another tool wrote, and applies externally added hooks only after you review them in its /hooks panel. After apothem install (and after an update that changes the hooks), restart CodeBuddy and confirm the Apothem entries in /hooks. The install prints this as a note. The documentation does not say whether the review repeats after each change, so open /hooks again after an update.

Your own hooks. The registration is merged into your file by key. Hooks and other keys you wrote stay as they were, a handler of yours under the same event and matcher stays beside Apothem's, and an update replaces only the handlers whose command runs the Apothem dispatcher (.apothem/support/hooks/dispatch.py with --contract codebuddy, whichever project path it was written under). A hook of yours that only shares the name, such as tools/hooks/dispatch.py in your project, or that runs python -m apothem.conformity.gate, is never taken for Apothem's. A file with comments or other JSON5 syntax cannot be rewritten without losing them, so the install reports a config.unparseable error for that file and leaves it untouched: remove the comments, or add the two entries yourself.

Turning the hooks off. Set APOTHEM_HOOKS_DISABLE=1 in CodeBuddy's environment to silence the Apothem hooks, or set CodeBuddy's own disableAllHooks setting to disable every hook.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared profile and renders the project rules file on every apothem install or apothem update run. CodeBuddy reads every *.md file under .codebuddy/rules/ as Markdown with optional YAML frontmatter (alwaysApply, paths, enabled) per the CodeBuddy Rules documentation; Apothem's file carries alwaysApply: true so the governance surface applies on every interaction. The frontmatter is the first content in the file and the Apothem-managed block follows it; text you add after the block is kept on every sync. The shared profile is the source of truth; project-local edits to the generated file are backed up before the next sync replaces the Apothem-managed content.

Compatibility notesCopy Anchor Link

CodeBuddy's rules surface is project-scoped under .codebuddy/rules/. The adapter writes a dedicated apothem-rules.md file that co-exists with any rules files the operator authors in the same directory. The CODEBUDDY.md project memory file, the committed .codebuddy/settings.json, and the project .mcp.json (MCP servers) are operator-owned; Apothem does not write them. CodeBuddy also documents slash commands; the adapter writes none and references the disciplines inside the rules file instead. It does write subagents and two hooks to the project (see Subagents and Hooks), and skills, and Apothem's commands as skills, to your user folder (see Files outside the project). When a project has no CODEBUDDY.md, CodeBuddy Code reads AGENTS.md as project memory, so an AGENTS.md another adapter writes reaches CodeBuddy as well. The vendor surface conventions the adapter relies on are pinned at src/apothem/harnesses/codebuddy/STANDARD-CONVENTION-PIN.md, snapshotted against the live CodeBuddy documentation.

CodeBuddy documents ~/.codebuddy/skills/ for user skills and does not mention ~/.agents/skills/, so the install writes the CodeBuddy folder and not the cross-tool one. That folder is read by CodeBuddy alone. Its skills page lists disable-model-invocation, user-invocable, and allowed-tools, and lists no metadata or argument-hint key; Apothem has not confirmed that CodeBuddy accepts them.

VerificationCopy Anchor Link

apothem verify --harness codebuddy --project /path/to/project

The verify command confirms that:

1. The native config exists at the expected path.
2. The managed rules file is present and non-empty.
3. The hook registration .codebuddy/settings.local.json exists, is non-empty and parses as JSON, and the hook scripts are in .apothem/support/hooks/. The file must hold a handler that runs the Apothem dispatcher (the check does not run it), so a file that was reverted or emptied no longer verifies.
4. The .codebuddy/agents/ folder exists. The check is on the folder, not on each helper file in it; the command apothem diff --harness codebuddy --project /path/to/project lists the helper files that are missing or out of date.
5. Every Apothem skill folder is in place with a SKILL.md, whichever install wrote it, and no skill folder with an Apothem name belongs to something Apothem did not write. A failed check names the missing or foreign folders.
6. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness codebuddy --project /path/to/project

Re-derives the project rules file from the current shared profile state. install and update are idempotent — re-running overwrites the managed file with the latest rendered content.

The update also rewrites any skill folder whose files differ from the current ones. If you installed with an earlier release that wrote no skills, the update adds them. It rewrites subagent files that differ from the current ones, and adds any that are missing. It also refreshes the hook scripts and the Apothem handlers in .codebuddy/settings.local.json, leaving your own entries alone; restart CodeBuddy and check /hooks again afterwards.

UninstallingCopy Anchor Link

apothem uninstall --harness codebuddy --project /path/to/project

Removes the Apothem block from apothem-rules.md and keeps any other text in it. The file is deleted only when nothing else remains in it. Before the change, a timestamped copy of the file is saved under ~/.apothem/backups/; no backup file is left in the project. The shared profile YAML and the Apothem engine are unaffected.

The uninstall also removes the subagent files it wrote in <project>/.codebuddy/agents/ and keeps any other file there; the folder is removed when it is left empty. It removes the Apothem hook handlers from <project>/.codebuddy/settings.local.json, recognising them by the dispatcher path in their command, and keeps your own hooks and keys. The file is deleted only when Apothem created it and nothing else remains in it. The hook scripts in <project>/.apothem/support/hooks/ go too. It removes the skill folders it wrote in ~/.codebuddy/skills/ and the rules and templates in ~/.config/apothem/, but only when no other Apothem install still uses them. Another project, or another tool that shares the folder, may. In that case the uninstall keeps the folders, prints which install uses them, and the last uninstall removes them. Files you added to those folders stay, and a folder left empty is removed. Each folder is backed up under ~/.apothem/backups/ before it is removed.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI