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. 229 unit tests and ten
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.
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).:statuslinewrites the one JSON file theagent-statuslinerenderer reads for every agent's status line, and that renderer's own--checkvalidates it before anything is written.- Claude Code plugins are installed through
claude pluginfrom a GitHub, git, directory or hosted marketplace, user-wide or per project; a git marketplace can be pinned to a branch, tag or commit with:ref,:version :latestupgrades a plugin when its marketplace moves, and:buildbuilds each new install (Claude plugins). :agentslinks Claude Code subagent definitions from a skill pack into~/.claude/agentsor a project's.claude/agents, and removes only the links it made (Claude subagents).- 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.
- Codex's nested tables are declarable too: keymap, presets and the native footer
(Codex TUI), and
[permissions.<name>]profiles (permission profiles). Hooks are declarable for Claude Code and Codex; vendor hooks in the same file are left alone (hooks). - 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, every MCP header, every env value it cannot show is no secret, and every argument after a credential-looking flag, which takes a reference as env does; 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, plus python3 3.11+ (stdlib
tomllib) to read and check TOML configs such as Codex's: agentctl tries python3.15 down to
python3.11, then python3, or uses AGENTCTL_PYTHON. 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 and awl's user-wide skills and codex's settings, where other kinds are reported, not written. One author, no tagged releases; report vulnerabilities privately as SECURITY.md describes.
- Pi, OMP, Kimi and Antigravity have no project-level MCP config, so a project-scoped
server is skipped for them with a warning. Codex writes it to the project's
.codex/config.toml, which Codex reads only for a trusted project. - 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. - Removing a project from the config leaves its project-scoped MCP entries behind.
bb testRan 229 tests containing 1682 assertions.
0 failures, 0 errors.
…
all gui 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, Codex TUI and permission profiles, GUI, MCP scope, Kimi, DeepSeek Harness, hooks, extensions, shared status line, 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.
