Provisions settings, MCP servers, skills and memory for the coding-agent CLIs on your machine from one EDN file.
Stage: alpha · Target: personal, published as-is · License: Apache-2.0
Install · Usage · Comparison · Limitations · Guide · Design and DSL
agentctl gui on a demo config in a scratch home with stub CLIs, captured with headless Chrome by capture-gui.sh.
Warning
Alpha. Config keys change without migration: :#let became :#def with no alias, and an
old file's $name references fall back to environment variables. 170 unit tests and five
end-to-end suites pass in CI, but no apply! over a whole config on a real home has been done
yet. Beta when that run is verified and a locked Bitwarden vault no longer drops an MCP
secret silently (see Limitations).
Each coding-agent CLI keeps its settings, MCP servers, skills and memory in its own files and
formats, so running several of them means repeating every change by hand in each and watching
the copies drift. ruler and
rulesync generate each agent's files from a rules
directory kept in the project. agentctl treats the machine itself as the infrastructure: one
~/.config/agents.edn declares user-wide and per-project state, apply prints a Terraform-style
plan, and apply! edits the files the CLIs also rewrite at runtime in place, by key or TOML
segment.
- Covers Claude Code, Codex, Pi, OMP, Antigravity (
agy), Kimi Code, the DeepSeek Harness (dsh) and Simon Willison'sllm; a tool whose CLI is not installed is skipped. applywrites nothing, not even state or directories, and exits 2 on drift, so it can run from cron or CI.apply!backs up every file before its first write in a run, under~/.config/agentctl/backups/<stamp>/, and removes only resources recorded in~/.config/agentctl/state.edn, plus project skill links that a global skill declaration supersedes (project skills).- TOML is edited segment by segment and JSON and YAML by key path, and MCP servers go through each CLI's own subcommand, so keys a CLI writes for itself survive.
- Secrets are
$ENV_VARor!bw://folder/item/fieldreferences resolved at apply time; a locked vault or unreachable endpoint is reported as unknown.importredacts credential-shaped values; review its output before sharing a config.
Compared with ruler v0.3.46 and rulesync v43.8.2, from their READMEs and the rulesync CLI reference.
| agentctl | ruler | rulesync | |
|---|---|---|---|
| Targets | 8 agent CLIs | 30, including an AGENTS.md pseudo-agent |
65, including plugin and IDE variants |
| Source of truth | ~/.config/agents.edn, user and project entries in one file |
.ruler/ per project, ~/.config/ruler as fallback |
.rulesync/ per project, --global mode |
| Manages | settings, MCP servers, skills, memory, providers, hooks, Claude plugins | rules, MCP servers, skills, subagents | rules, ignore files, MCP servers, commands, subagents, skills, hooks, permissions |
| Drift check | apply exits 2 on drift |
--dry-run preview |
generate --check |
| Removal | only resources recorded in its state file | revert restores .bak files and deletes generated ones |
generate --delete sweeps its managed paths; --retire-targets for a dropped tool |
| Runtime | Babashka | Node.js 20.19+, 22.12+ or 23+ | Node.js, or a single binary |
ruler or rulesync is the better fit for rules committed to a team repository, or for an agent outside agentctl's eight.
Requires Babashka (bb) and git. Optional: bw for !bw:// secret
references, gh for [:gh …] skill packs, and npx for skills placed in a repository (run
through the skills CLI).
git clone https://github.com/artmsh/agentctl.git
cd agentctl
ln -s "$PWD/agentctl" ~/.local/bin/agentctl # any directory on PATH; the launcher follows links
agentctl --helpDeclare the desired state in ~/.config/agents.edn. :in :all is user scope; a path such as
"projects/sample" places the entry in that repository only:
{:settings [{:model "sonnet" :acli [:claude] :in :all}]
:mcps [{:id :search :cmd "search-mcp --stdio" :acli [:claude :codex] :in :all}]
:memory [{:from "~/notes/AGENTS.md" :mode :symlink :in :all}]
:skill-packs {[:uri "file://$HOME/projects/skills-repo"] {:alias skills-repo}}
:skills {[skills-repo "review"] {:in "projects/sample"}}}agentctl validate # report on config and environment; exit 1 on errors
agentctl apply # read-only plan; exit 2 when drift exists
agentctl apply! # back up, then converge; asks first unless --yes…
CLAUDE
+ mcps/search
search-mcp --stdio
+ memory/AGENTS.md
!ln -s ~/notes/AGENTS.md ~/.claude/CLAUDE.md
+ settings/{$schema model}
create `~/.claude/settings.json`:
+ $schema: "https://json.schemastore.org/claude-code-settings.json"
+ model: "sonnet"
…
11 to add, 0 to change, 0 to remove, 2 unchanged
+ creates, ~ changes, - removes and = is unchanged; a line starting with ! is a shell
command the run will execute (reading a plan).
| Command | Does |
|---|---|
apply / apply! |
Preview the plan / apply it |
validate |
Check the config and the environment; --deep also probes the network |
import / import! |
Print / merge the config the current environment implies |
state |
List the resources agentctl owns |
gui |
Edit the config in a browser beside its live dry run |
-t TOOL, -k KIND and -p PATH narrow a run, and inside a declared project apply already
plans only that project unless you pass --all (how the working directory scopes a run).
--only KIND/ID (say --only skills/review) plans one entity wherever it is placed, and --user
plans user scope alone; a narrowed run never prunes what lies outside it
(applying one entity).
--host NAME runs apply, apply!, validate or state against a machine declared under
:hosts, over SSH, while AGENTCTL_HOME points every managed path, and the CLIs agentctl
drives, at a scratch tree for testing. agentctl gui serves the screen above on 127.0.0.1
behind a per-run token in the URL it prints, and Apply is its only control that writes
(GUI).
For one person running several coding-agent CLIs who wants their settings, MCP servers, skills, memory and providers in one reviewed file. Not for agent CLIs other than the eight above (an unknown tool is a config error; see Comparison), or for remote hosts beyond codex's user-wide skills, where other kinds are reported, not written. One author, no tagged releases; report vulnerabilities privately as SECURITY.md describes.
- Codex, Pi, OMP, Kimi and Antigravity have no project-level MCP config, so a project-scoped server is skipped for them with a warning.
- The DeepSeek Harness keeps settings, MCP servers and providers in Cordis patch files that
agentctl does not write;
:dshentries there are reported byvalidateand the plan. - With a locked Bitwarden vault,
apply!writes an MCP server without the header or env var that carried the secret, and the nextapplyshows no drift. - Removing a project from the config leaves its project-scoped MCP entries behind.
bb testRan 170 tests containing 1014 assertions.
0 failures, 0 errors.
…
all plugin e2e checks passed
tests/run.sh stubs every agent CLI and points AGENTCTL_HOME at a temp dir, so the suite does
not touch your configuration; CI runs the same command on Ubuntu. docs/images/capture-gui.sh
regenerates the screenshot.
- docs/GUIDE.md: working-directory scope, GUI, MCP scope, Kimi, DeepSeek Harness, hooks, extensions, Claude plugins, project skills, remote hosts, reading a plan.
- docs/AGENTCTL.md: design rules and every DSL key, including the legacy map form that examples/agents.edn uses.
- docs/SCOPE-DSL.md: the entity-first DSL and its
:inselector. - DESIGN.md: the GUI's visual system.
