Skip to content
artmshPublic

About

Provisions settings, MCP servers, skills and memory for the coding-agent CLIs on your machine from one EDN file.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

agentctl

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
CI
Install · Usage · Comparison · Limitations · Guide · Design and DSL

Screenshot of agentctl gui: config controls on the left, the live dry-run plan on the right.

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).

Rationale

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.

Features

  • Covers Claude Code, Codex, Pi, OMP, Antigravity (agy), Kimi Code, the DeepSeek Harness (dsh) and Simon Willison's llm; a tool whose CLI is not installed is skipped.
  • apply writes 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_VAR or !bw://folder/item/field references resolved at apply time; a locked vault or unreachable endpoint is reported as unknown. import redacts credential-shaped values; review its output before sharing a config.

Comparison

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.

Install

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 --help

Usage

Declare 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).

Scope

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.

Limitations

  • 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; :dsh entries there are reported by validate and the plan.
  • With a locked Bitwarden vault, apply! writes an MCP server without the header or env var that carried the secret, and the next apply shows no drift.
  • Removing a project from the config leaves its project-scoped MCP entries behind.

Development

bb test
Ran 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.

Documentation

  • 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 :in selector.
  • DESIGN.md: the GUI's visual system.

About

Provisions settings, MCP servers, skills and memory for the coding-agent CLIs on your machine from one EDN file.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages