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

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).
  • :statusline writes the one JSON file the agent-statusline renderer reads for every agent's status line, and that renderer's own --check validates it before anything is written.
  • Claude Code plugins are installed through claude plugin from 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 :latest upgrades a plugin when its marketplace moves, and :build builds each new install (Claude plugins).
  • :agents links Claude Code subagent definitions from a skill pack into ~/.claude/agents or 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_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, 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.

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

Limitations

  • 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; :dsh entries there are reported by validate and the plan.
  • Removing a project from the config leaves its project-scoped MCP entries behind.

Development

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

Documentation

  • 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 :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