agent-session-loop

Agent Session Loop (asl): run split agent session plans one session at a time — prepare, preflight, run, supervise, review, and inspect them — plus the portable ASL Workbench and the shared planning and supervision skills.

Status: a personal tool, published as-is under the MIT License. It is built around the author's own setup (macOS, the Claude Code, Codex and Copilot CLIs). Issues and pull requests are not monitored; fork freely.

Setup

git clone https://github.com/sglavoie/agent-session-loop.git
cd agent-session-loop
just all

ASL needs Python 3.14 or later as python3; the wrapper refuses an older interpreter with a message naming the one it found. The install links asl into ~/.local/bin, so that directory must be on your PATH (export PATH="$HOME/.local/bin:$PATH").

just all (the same as just install) runs install.py, which links:

• ~/.local/bin/agent-session-loop and ~/.local/bin/asl to the wrapper in bin/.local/bin/
• every directory under skills/ into the skills/ directory of each harness root that already exists: ~/.claude, ~/.codex and ~/.copilot, plus any further Claude Code profile named by CLAUDE_CONFIG_DIR or by ASL_CLAUDE_CONFIG_DIRS (a :-separated list, for example export ASL_CLAUDE_CONFIG_DIRS=~/.claude-work). A harness root that does not exist is reported as skipped and never created, and a root outside your home directory is ignored.

It then renders the ASL startup card into the context file of each discovered harness root (see just sync-skills below), creating that file when it does not exist yet, for example ~/.copilot/copilot-instructions.md. Running ./install.py on its own only links; it names any context file that is still missing so you can render it with just sync-skills.

Each link is an absolute symlink into this checkout, replaced atomically, so a running companion, bridge or supervisor that execs asl mid-install never finds it missing. An existing symlink (say, one a different checkout installed) is retargeted; a real file or directory is never overwritten. The wrapper directory and each harness's skills/ directory must resolve inside the selected home. A nested symlink pointing outside it stops the install before any links are changed or stale links are pruned. just install-dry-run shows what would change, including which harness roots were found and which startup cards are stale, without touching anything.

Every directory under skills/ needs a SKILL.md. Shared support directories that intentionally have none (such as skills/references/) must be listed in SUPPORT_DIRS in agent_session_loop/install_verify_common.py, which install.py and just verify-asl-install share. A directory holding nothing but cache residue (__pycache__/, *.pyc, .DS_Store), which is what removing a skill from git leaves behind, is skipped with a note and any installed link to it is pruned; delete it to silence the note. Any other directory without a SKILL.md fails the install as a malformed skill.

just sync-skills re-links the skills and renders the ASL startup card into the context file of each discovered harness root (~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, CLAUDE.md in every extra Claude profile, and ~/.copilot/copilot-instructions.md) and into skills/asl/references/supervisor-context.md. The card lives inside <!-- ASL_CONTEXT_START ... --> / <!-- ASL_CONTEXT_END --> markers, so any other startup instruction in those files is left untouched. Run just check-startup-context to report stale blocks without rewriting them; it lists a context file that does not exist yet as missing: rather than stale:.

After changing ASL or its skills, run just verify-asl-install to confirm the active asl wrapper, the installed skill links, the installed ASL skill and helper, and the rendered startup card in every discovered harness root all resolve to this checkout. Set ASL_CLAUDE_CONFIG_DIRS in the shell that runs it too, or the extra profiles are not checked.

The launchd jobs ASL and the Workbench install (the maintenance job and the Workbench connector) are labelled com.sglavoie.*. Set ASL_LAUNCHD_LABEL_PREFIX (for example org.example) before installing them to use your own prefix; uninstall an existing job before changing it, or the old one is left behind.

First run

Check the installed harness CLI, prepare a plan, check the prepared plan's prerequisites, then run the command prepare printed:

asl harness-compat --harness claude
asl prepare PLAN.md --cwd "$PWD" --harness claude
asl doctor PLAN_DIR --harness claude
asl run PLAN_DIR --harness claude

asl harness-compat classifies the installed claude CLI against the tested version window without using any model; asl doctor needs a plan directory, so it runs once one exists, and checks the working directory, the harness executable, the next pending session and the prompt it would send.

asl prepare splits the source plan into a plan directory, PLAN_DIR above (under ~/.local/share/agent-plans/ by default), validates and baselines it, runs the final preflight that marks it loop-ready, and prints the exact asl run command for that directory; use the printed one rather than retyping it. Add --review-harness codex (any harness other than --harness) to end the run with a review session under a second harness. If preflight is not green, repair the plan and rerun asl prepare --resume PLAN_DIR. To have an agent supervise the run, hand that command to the asl skill (/asl asl run ... in Claude Code). The ASL operator guide covers each step.

Documentation

• docs/asl-guide.md — ASL operator guide: command families, live supervision, assurance, Agent Mux integration, releasing, and testing
• docs/agent-session-loop.md — the complete ASL reference
• agent_session_loop/README.md — package layout and internals
• asl_workbench/README.md — the portable Workbench package: module inventory, deployment, and portability boundaries

Related

• Agent Mux — the separate client (amx, the cockpit and its daemon) that talks to ASL over the bridge. Recipes such as just paired-release-gate, just asl-integration and just overseer-integration that the docs mention belong to that repository and run from its checkout.

Development

Testing

just test-fast
just test-portable
just test-all
just reliability-stress
just test-browser   # Workbench browser tests; needs Node and npm

Stdlib unittest only. CI (.github/workflows/) runs a portable Linux lane and the full suite on macOS, plus just test-browser when the Workbench shell or its browser harness changes. See Testing in the ASL guide for what each recipe covers.

just test-live-recovery codex probes the installed version without model use. Add --live --keep-workspaces --report /tmp/asl-recovery.json to exercise a runner crash during session 2, explicit predecessor cleanup, stale-lock unlock, and verified recovery from retained files with a fresh conversation. See crash-recovery acceptance for its pass criteria and limits. Ordinary CI uses a deterministic harness fixture.

Linting

just lint

Runs ShellCheck on all shell scripts (config in .shellcheckrc), then ruff check, ruff format --check, and mypy on the Python code (config in pyproject.toml).

Dependencies

• macOS for ASL itself: the full suite gates on it, and the scheduled maintenance job and the Workbench connector are launchd jobs. The core CLI and the portable lane also run on Linux (CI checks that), where asl maintenance install reports that no launchd job is possible. The portable Workbench service targets a Linux host under a systemd user unit.
• Python 3.14+ (asl_workbench stays importable on 3.13 for its remote host)
• git, just
• ruff, mypy, shellcheck for just lint
• At least one harness CLI for real runs: claude (Claude Code), codex or copilot. ASL launches whichever --harness names; the others are optional.

License

MIT