Apothem vs raw Zed config
Hand-maintaining Zed's flat .rules instruction file versus rendering it from Apothem's shared profile.
Zed reads agent instructions from a single flat .rules file at the project
root (alongside the AGENTS.md / CLAUDE.md family). Apothem's zed adapter
renders that file from the shared profile. This page contrasts hand-maintaining
that config against managing it with Apothem.
Effort comparison
| Task | Raw hand-config | Apothem-managed |
|---|---|---|
| Author instructions | Hand-write the .rules file | Rendered from the shared corpus |
Preserve a prior .rules | Remember to copy it aside yourself | The adapter backs up the existing file before replace |
| Keep rules aligned with other harnesses | Manual, per tool | Automatic on apothem update |
| Share reusable skills and commands | Hand-copy each skill folder into ~/.agents/skills/ and keep the copies current | Written to ~/.agents/skills/ by the adapter, one copy for every project, and refreshed on apothem update |
| Verify the config is correct | Manual inspection | apothem verify --harness zed --project <path> |
What Apothem manages
The zed adapter renders the shared rules into the flat project-root .rules
file. Zed has no PreToolUse hook, so guardrail intent lives in the rule prose
rather than a tool-call interception point. The global ~/.config/zed/AGENTS.md
instruction file and the .zed/settings.json MCP context-server block are
operator-owned and left untouched. Every change to the shared rules re-renders
the file on the next apothem update.
Migration path
- Run
apothem profile initto create the shared profile if you have not yet. - Move the instructions from your existing
.rules(and any project-specificAGENTS.mdcontent you want shared) into the shared corpus. - Run
apothem install --harness zed --project <path>to render the.rulesfile. Your prior.rulesis backed up first. - Run
apothem verify --harness zed --project <path>to confirm the config landed. - Use
apothem update --harness zed --project <path>for every later change.