agentic-setup

A template for running Claude Code as a small governed fleet of assistants instead of one chat window.

The pitch, in one line: an assistant you can leave unsupervised, because everything it does is gated, logged, and undoable.

This is a frozen pattern snapshot. It is shared as-is, not maintained as a product. There is no roadmap and no support. Fork it and make it yours. Everything in hubs/ and in the examples is fabricated.

The problem this solves

An assistant becomes genuinely useful at roughly the same moment it becomes risky. The useful version has your calendar, your mail, your repositories, and permission to work while you sleep. That is also the version that can send the wrong message, push to the wrong branch, or quietly rewrite a file you were relying on.

The common answer is to keep it in the chat window, approve everything by hand, and accept that it will never carry anything recurring. That works, and it caps the value at "faster typing".

This template takes the other path. Let it run unattended, and constrain what unattended means:

• Reversibility. Unattended work happens on agent/* branches, in draft folders, in append-only notes. The undo is deleting a branch.
• Gates. A short written contract lists what never happens without a human in the same session: sends, publishes, purchases, deletions, pushes to main.
• Auditability. Every unattended session ends by writing a report. Work without a report line did not happen.
• Self-maintenance. A periodic sweep checks the setup itself for drift, stale queue items, and scheduled jobs that stopped reporting.

There are many "second brain" folder templates. The part worth copying here is not the folders. It is the governance layer.

If you only read one file, read docs/autonomy-charter.md. It needs no terminal, no install, and no Claude Code — it is the contract that makes the rest worth wiring up, and it stands on its own as a policy document you could adapt at work.

The architecture in one page

Hubs. One directory per context: research, a side project, home admin. You launch Claude Code from the hub directory, so only that hub's config, skills, and memory load. Contexts that must not mix get separate hubs and one explicit line in the global config forbidding transfer between them. A context governed by an employer's or institution's data or AI policy gets the strictest treatment: the policy's rules become hub rules, and its protected material only ever meets tools that institution has approved.

The autonomy charter. The contract for unattended sessions. Allowed: agent/* branches, notes, drafts, queue and tracker updates. Forbidden without a same-session go-ahead: sending, publishing, purchases, deletions, pushes to main. Every rule is annotated with why, and the rationale is always the same shape: could you undo this in the morning.

Work queues. A WORKQUEUE.md per hub, the handoff surface between you and the overnight worker. [auto-ok] means an unattended session may execute it. [needs-you] means prepare only: draft, scaffold, research, then stop.

The tracker. One tracks.md at the user level. One section per multi-month commitment, with dated milestones and a status computed from rules rather than feelings. Exactly one skill writes it.

The night shift. A scheduler runs one headless session per night against one hub from a rota. The wrapper grants a least-privilege tool allowlist, logs everything, and posts a desktop notification with the run's one-line result. The session's last act is the report.

The drift sweep. A monthly self-audit: config that has drifted from its mirror, queue items nobody has touched in a month, sessions waiting on you for more than a week, scheduled jobs that did not write their last report.

What you get, concretely: a one-minute morning brief, overnight work you can review over coffee and drop with a branch deletion, and a system that tells you when it has started to rot.

Quickstart

Roughly a weekend, most of it spent writing your own content rather than wiring anything.

0. Clone it somewhere stable. The scripts and the launchd job default to $HOME/agentic-setup. Any path works if you update ROTA_FILE in scripts/night-shift.sh and the paths in the plist to match.

1. Copy the global config.

cp CLAUDE.template.md ~/.claude/CLAUDE.md   # Claude Code's user-level config file

Fill in every <angle-bracket> placeholder. Delete what does not apply. Keep it under two screens: every line in this file is loaded into every session in every context.

2. Decide your hubs. Three or four. One directory each, wherever you keep projects. If two of your contexts must not mix, they are two hubs, and you write the separation line in the global config now rather than later.

mkdir -p $HOME/hubs/<hub-a> $HOME/hubs/<hub-b>
cp hubs/example-hub/CLAUDE.md   $HOME/hubs/<hub-a>/CLAUDE.md
cp hubs/example-hub/WORKQUEUE.md $HOME/hubs/<hub-a>/WORKQUEUE.md

Then rewrite both. The example hub is fictional and exists only to show shape.

3. Read the charter. docs/autonomy-charter.md, all of it, before you schedule anything. Copy the compact version into your global config. If you disagree with a boundary, move it deliberately and write down why, rather than discovering the disagreement at 03:00.

4. Install the skills. Copy skills/* into ~/.claude/skills/ and edit the placeholder source lines: calendar, mail, notes location, tracker path, key people. One honest prerequisite this repo does not cover: the skills read whatever sources your assistant can actually reach. Connecting mail and calendar to Claude Code (via MCP servers or built-in connectors) is its own setup, done before this step — until then, the morning brief works with just the tracker, the queue, and the night reports, which is a fine way to start anyway.

5. Start the tracker. Create tracks.md next to your global config with two or three real tracks. Format: docs/tracker-format.md. Two is enough to start; the tracker is worth having the day it tells you something you did not already know.

6. Run the pieces by hand for a week. Morning brief in the morning, track when something completes, setup-review once. Do not schedule anything yet. You are checking whether the output is worth reading, and you will edit the skills a lot in this week.

7. Then schedule the night shift.

cp scripts/rota.example scripts/rota   # edit: weekday -> hub directory
# macOS
cp scripts/com.example.night-shift.plist ~/Library/LaunchAgents/
# replace HOME_PLACEHOLDER inside the file, then:
launchctl load ~/Library/LaunchAgents/com.example.night-shift.plist
# Linux: the equivalent cron line is in the header of scripts/night-shift.sh

Start with one hub, one night a week. Read the report every time for a month. Widen only after a run has surprised you and the surprise was cheap.

File tour

File	What it is
CLAUDE.template.md	User-level global config. Placeholders throughout. The constitution.
docs/autonomy-charter.md	The unattended-work contract, every rule annotated with its rationale.
docs/tracker-format.md	Tracker grammar, the three status values, and the slippage rules.
docs/memory-rules.md	What belongs in auto-memory, in config, and in notes, and how to promote between them.
hubs/example-hub/CLAUDE.md	A fictional hub config: local rules, layout, what is never [auto-ok] here.
hubs/example-hub/WORKQUEUE.md	A fictional queue showing the tag grammar.
skills/morning-brief/SKILL.md	Read-only start-of-day brief. Seven fixed sections.
skills/track/SKILL.md	The only writer of tracks.md. Update, recompute, add, publish.
skills/night-shift/SKILL.md	The unattended worker. Procedure and report format.
skills/setup-review/SKILL.md	The monthly drift sweep.
scripts/night-shift.sh	Scheduler wrapper: rota lookup, tool allowlist, logging, notification, report check.
scripts/rota.example	Weekday to hub-directory mapping.
scripts/com.example.night-shift.plist	launchd job. A cron line is in the script header.

The conventions, so the files read consistently

• Queue tags: [auto-ok], [needs-you], not-before: YYYY-MM-DD, proposed-by-agent.
• Track statuses: on-track, at-risk, slipped.
• Unattended branches: agent/*, and agent/night-<date>-<hub> for scheduled runs.
• Night report sections: ## Done, ## Proposed, ## Blocked on you.
• Dates are ISO, YYYY-MM-DD, always absolute.

If you rename any of these, rename them everywhere. The skills read each other's output, and a tag that exists in two spellings is a tag that silently stops matching.

What this does not do

It does not make the assistant reliable. It assumes a capable system that will occasionally be confidently wrong, and it arranges the consequences so that being wrong overnight costs a branch deletion and two minutes of reading.

It does not remove you from the loop. Decisions, sends, publishes, and money stay yours. The overnight work is preparation, and preparation is most of the work.

It does not replace judgment about what should be automated at all. Some recurring chores are better dropped than delegated.

Adapting it

Fork it and change it. The parts most people should change first are the hub list, which is personal, and the exact boundaries in the charter, which depend on what you have connected and how much you can afford to undo.

The parts to change last, if at all, are the four structural rules that everything else rests on: unattended work is reversible, the report is mandatory, the tracker has one writer, and hub context does not travel.

Upstream repository: github.com/ramenskiy/agentic-setup. The companion write-up is An Assistant You Can Leave Unsupervised; contact via ramenskiy.com.

License

MIT. See LICENSE.