agent-config

An opinionated agent configuration with shared instructions and skills for
Claude Code, Codex, and Grok. Claude still consumes the whole repository as its
~/.claude directory; thin support links let the other harnesses read the
same policy and skill sources, and let Codex add validated linked-worktree Git
access, without duplicating configuration.

Two ideas run through all of it:

• Sessions are a fleet, not a window. A dozen concurrent Claude Code
  sessions is normal. They need a registry, an urgency order, a way to search
  across them, and a way to bring back the ones that died.
• A transcript is the only artifact that can't be regenerated. Code can be
  rewritten; a conversation can't. So durability gets real engineering, not
  hope.

It is Linux + systemd + WezTerm. Nothing here is portable to macOS or
Windows without work, and the interesting parts assume all three.

What's in here

The parts most worth stealing

The fleet tab bar (FLEET.md). Every tab is one session, colored
by how long it has been waiting on you — a continuous truecolor gradient on a
logarithmic age scale, with a dynamic ceiling so the reddest tab is always the
most-neglected one relative to the rest. Wait age runs on an "awake clock"
that stops during suspend, so resuming your machine doesn't turn the whole bar
red. Ctrl+Shift+Space opens a fuzzy picker sorted by urgency;
Ctrl+Shift+F greps live transcripts and jumps to the match.

The visible bar is only a front-end. Underneath, hooks/session-state.sh writes
state/<session_id>.json from Claude and Codex lifecycle events, and
bin/claude-sessions --json joins those into an urgency-sorted registry. Any
terminal could render it.

The registry is not Claude-only. Codex and Grok sessions run in the same tabs and
compete for the same attention, so each vendor gets a small adapter returning the
same record shape plus a vendor tag — and the picker, the tab bar, the attend
key, cross-session search, the transcript reader and the post-reboot restore all
work on them without knowing which vendor they are. Vendors that publish no
session registry are found by process and matched to their own transcript store.
Codex reports exact status through its native hooks; vendors without hooks fall
back to an estimate based on transcript activity.

The durability layer (bin/README.md). Claude appends each
turn to a transcript, but the kernel can hold those writes in the page cache for
seconds, and ext4's default data=ordered journals metadata but not data — so
an unclean shutdown can roll back whole sessions. This happened, twice, and the
write-up is the most directly useful thing in the repo. A 20-second timer
fsyncs and mirrors recent transcripts; a 60-second timer records which sessions
are live, with a boot-grace guard and a "cliff guard" for suspend-freezes, so a
post-crash tick can't overwrite the pre-crash set before you restore from it.

The account router (bin/claude-acct). Two subscriptions, one claude
command: every launch probes both accounts and starts the session on whichever
has more headroom — scoring usage against each window's next reset rather than
its raw percentage, because 60% spent with twenty minutes to refill is cheaper
than 40% that has to last four hours. It enforces limits rather than working
around them: when every account is capped it refuses and names what else is
installed instead, and a session that hits its cap mid-turn hands the
conversation to the account with room rather than ending (both accounts share
one transcript store, so the conversation itself can move). One person, two paid
subscriptions, no shared credentials. It reads an undocumented
api/oauth/usage endpoint — the same one /usage renders — so treat that part
as liable to change without notice.

workspace (skills/workspace/SKILL.md). One primitive for isolated
parallel work: a git worktree, a dev-server port, a copied env file, an isolated
database, and a state record — created, resumed, and torn down as a unit. The
other skills (feature, propose, review-pr) call it instead of each
reimplementing worktree setup. feature uses that branch for implementation
and review, then integrates the remote's actual default branch, reruns the
approved checks, pushes the verified commit directly to default, waits for CI,
and removes the landed branch and worktree. PRs and parked branches are not
completion paths in this workflow. Its synchronous command runner captures
stdout and stderr through bounded, immediately-unlinked files and a trusted
Python bridge. This avoids Node's captured-pipe EPERM inside Codex's offline
Linux sandbox without broadening network or temporary-directory permissions,
leaving capture artifacts, or allowing unbounded command output.

The review agents (agents/, skills/review-*). Five specialist reviewers —
security, simplicity, UI, visual, QA — that share one contract rather than one
prompt. Each declares its authority (what it may and may not do: the QA
tester never reads source, the simplicity reviewer never questions requirements
that were already agreed), carries a single core question it asks of every
file, grades findings MUST FIX / SHOULD FIX / CONSIDER, and ends with "what
I couldn't evaluate" — the blind-spot disclosure that makes a clean review
trustworthy instead of merely quiet. review-pr runs them over a PR, a
worktree, or an explicit file list; each also runs standalone.

The simplicity and UI reviewers read their criteria from files in this repo
through the neutral ~/.config/agent-config source alias, so the standard being
applied is editable text rather than something buried in a prompt.

lib/doctor.mjs. Resolves every cross-reference in the config — file paths
embedded in skills, agents, hooks, and instructions, settings.json env values,
and all harness support links — against what is actually on disk. It runs at
session start and on pre-commit, turning silent breakage (a renamed agent file,
a moved doc, a missing Codex link) into a loud, early failure.

Install

git clone <this repo> ~/projects/agent-config
~/projects/agent-config/bin/agent-config-install
~/projects/agent-config/bin/agent-config-install --check

# One-time Codex permission migration: Git works by default.
~/projects/agent-config/bin/codex-git-access enable

# After restarting Codex, run this inside the new session to prove its active
# sandbox can write Git metadata.
~/projects/agent-config/bin/codex-git-access check ~/projects/agent-config

# Ubuntu 24.04 only: permit Codex's bubblewrap workspace sandbox without
# disabling AppArmor's global unprivileged-user-namespace restriction
~/projects/agent-config/bin/install-codex-bwrap-profile
~/projects/agent-config/bin/install-codex-bwrap-profile --check

mkdir -p ~/.claude/state ~/.config/wezterm
ln -s ~/.claude/wezterm/wezterm.lua ~/.config/wezterm/wezterm.lua

# timers for durability + resurrection
mkdir -p ~/.config/systemd/user
ln -s ~/.claude/systemd/user/*.{service,timer} ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now claude-snapshot.timer claude-transcript-sync.timer

# integrity check + the pre-commit leak guard
node ~/.config/agent-config/lib/doctor.mjs
ln -sf ../../hooks/pre-commit ~/.claude/.git/hooks/pre-commit

# keep auto mode's generated infra dossier out of git (see below)
git -C ~/.claude config filter.strip-automode.clean "node lib/strip-automode.mjs"

The installer derives the repository path from its own location and creates
exactly seven links: the neutral ~/.config/agent-config source alias,
~/.claude, the managed ~/.local/bin/codex launcher, Codex's
~/.codex/AGENTS.md and ~/.codex/hooks.json, Grok's ~/.grok/AGENTS.md, and
the shared ~/.agents/skills. Codex and Grok both point directly to the canonical
policy; Grok discovers Claude instruction files but does not expand Claude's
@... imports. The installer is idempotent and refuses to replace unrecognized
files, directories, or links. The only automatic migration is the former
~/.codex/AGENTS.md -> ../.claude/CLAUDE.md link. It refuses noncanonical HOME
paths, invalid source targets, and symlinked or non-directory configuration
parents before changing the home directory.

Run it as the target user, never through sudo. It is a single-user bootstrap
tool and assumes another process is not concurrently rewriting the same
configuration paths; it is not a security boundary against processes already
running as that user.

On Ubuntu systems that set kernel.apparmor_restrict_unprivileged_userns=1,
Codex's workspace-write sandbox needs the included path-specific AppArmor
profile. The separate installer copies it to /etc/apparmor.d/codex-bwrap,
loads it, and runs a real sandbox probe. It refuses to overwrite different
existing policy. This keeps the global user-namespace restriction enabled and
grants the capability only when /usr/bin/bwrap runs.

Codex's legacy workspace-write sandbox deliberately protects .git as
read-only, so it can edit source but cannot commit. codex-git-access enable
replaces that legacy policy with four permission profiles: Git/no-Git crossed
with network on/off. Those profiles carry intent and network policy; the managed
launcher adds write access only for exact Git directories it has validated.
The static profile deliberately contains no workspace-relative .git rule, so
starting Codex in a non-repository umbrella cannot create a synthetic .git
mount target there. The user default becomes Git-enabled without granting write
access outside validated repositories. Hidden persistence surfaces remain
protected: top-level config/hooks, pointer checkouts and their resolved Git
directories, initialized submodule pointers, object-alternate pointers, linked-worktree
pointer/config files, and every existing project .codex/config.toml policy
source stay read-only while ordinary Git metadata is writable. Both temporary-directory
exclusions and approval_policy = "never" remain unchanged. The command recognizes only the
legacy shape used here, preserves unrelated TOML text, validates the result,
creates a private backup under ~/.local/state/agent-config/backups/, and is
idempotent. Config reads are capped at 1 MiB and opened nonblocking, so a large
file or special-file substitution cannot strand the migration. It refuses
ambiguous or conflicting policy instead of guessing.

Trusted project config has higher precedence than the user default. To keep one
checkout's Git metadata read-only without changing its network posture, run:

~/.config/agent-config/bin/codex-git-access opt-out /path/to/project

If a project already has a legacy local workspace-write policy, name it on
the enable command to migrate that local policy while preserving its explicit
network setting. Projects without local policy simply inherit the user default.

Run codex-git-access check [PROJECT...] from a newly started Codex session to
validate the installed profiles. For each checkout it creates and removes one
uniquely named inert file inside the resolved Git directory, proving the active
sandbox can write Git metadata without changing the index or refs. When Codex
starts from a non-Git umbrella such as ~/projects, the managed launcher scans
ordinary descendants recursively within hard directory, entry, and repository
ceilings, then adds each eligible checkout as an exact runtime workspace root.
That makes the user-level Git
default effective for discovered child repositories; a discovered child-root
no-git policy keeps that repository's metadata read-only, while a no-git
policy at the umbrella root disables Git for every child. Network policy is
session-wide, so project offline profiles are security boundaries only on a
direct project launch. If an online umbrella discovers any offline child or
shared worktree policy, the launcher tightens the whole fleet session to offline
and keeps eligible Git roots enabled. It cannot prove no offline root appeared
after startup. The scan has directory, entry,
repository, captured-output, elapsed-time, and runtime-profile-size budgets. It
skips generated dependency/build trees while retaining workspace-worktree
coverage, validates ordinary roots plus every shared worktree policy/config/hook
layer, skips the fleet's archived trash tree, and never treats a pointer-file worktree or submodule as an ordinary
checkout. A local core.fsmonitor, a Git config include, an unsafe policy or
hook, an unexpected external submodule Git directory, or any exhausted budget
makes the entire session read-only rather than applying partial rules. Every
candidate is validated and the complete runtime profile is built, including
individual and aggregate argument-limit checks, before any repository is
changed. After that transaction-like preflight, the launcher
materializes only standard empty optional Git metadata paths needed for the
read-only guards; repositories that opt out of Git access remain untouched.
For a linked worktree, the installed launcher first validates Git's .git,
commondir, gitdir, and worktree-list pointers. It then starts Codex with an
ephemeral profile that keeps the external common Git directory read-only and
opens only shared objects/refs/logs plus that worktree's own admin directory.
The source .git pointer, checkout index and HEAD, common config/hooks, current
admin pointers/config, and sibling worktree admin directories remain read-only.
Initialized submodule pointers are checked recursively on direct and umbrella
launches. Shared objects and refs are necessarily shared between linked
worktrees; use separate clones when those must be isolated too. Creating or
removing worktrees is intentionally unavailable inside a managed Git session
because .git/worktrees is a persistence boundary. Any automatic-augmentation
validation failure also makes the whole workspace read-only rather than leaving
failed policy or nested Git control paths writable.

The launcher derives HOME from the account database, removes project-set
XDG_CONFIG_HOME, accepts only a trusted CODEX_HOME outside project input,
and bounds every Git subprocess. An account-home launch must use the default
~/.codex and is forced read-only so the session cannot replace the trusted
Codex/Node install or shell startup files. The user's pre-existing global Git
configuration and non-hook repository-local command settings are trusted only
after every effective config origin is validated. Config includes and
core.fsmonitor are rejected at every scope, while a custom hooks path is
accepted only after its directory and every active hook are validated and
protected exactly.
Explicit Codex sandbox, profile, filesystem/network permission, or --add-dir
overrides bypass this automatic augmentation. A trusted project config may
select only default_permissions; any other project-local permission key makes
automatic augmentation fail closed. Permission changes and launcher installs affect only new Codex
sessions. See OpenAI's current
permission-profile and
configuration-precedence
documentation for the underlying model.

Project instruction migrations

bin/project-instruction-migrate is the transaction used for standards-first
project rollouts. A runtime JSON manifest names exact project roots, expected
hashes for the existing CLAUDE.md and AGENTS.md, hash-checked replacement
payloads, and any exact obsolete-file deletions. report is read-only;
apply refuses drift or dirty planned Git paths, permits unrelated dirty work,
writes every selected project as one rollback-capable transaction, and stores
a private backup under ~/.local/state/agent-config/project-migrations/;
restore refuses to overwrite edits made after the migration. Non-Git umbrella
directories are supported without treating their nested repositories as the
umbrella root. Live fleet manifests are ignored runtime state, not durable
repository policy.

That last line matters. Auto mode writes a summary of this machine's
infrastructure — production hostnames, where secrets live, how deploys work —
into settings.json under autoMode.environment. It belongs in the working
file and never in a public repo. The clean filter (lib/strip-automode.mjs,
wired up by .gitattributes) strips it on the way into git, so staging
settings.json cannot carry it even if you forget; hooks/pre-commit refuses
the commit as a backstop when the filter isn't configured. Both are needed: the
filter is per-clone git config, which a fresh clone does not inherit.

settings.json wires Claude's hooks and status line; codex/hooks.json wires
the corresponding Codex lifecycle events. Shared reference paths use the
neutral ~/.config/agent-config alias. Codex requires one-time review of a new
or changed hook definition through /hooks before it will run.

Requirements: WezTerm, python3, jq, node, systemd-user, and ideally
ripgrep (plain grep is the fallback).

Optional, not included: claude-grep (from a separate personal repo at
~/projects/claude-beep) marks a found session's terminal tab. /find-session
searches with the bundled bin/claude-search and only reaches for claude-grep
when it is present, so nothing here breaks without it.

Caveats. This is one person's live config, published because parts of it are
generally useful — not a framework. It assumes a ~/projects/<name> layout, and
settings.json runs with a broad permission allowlist and defaultMode: auto,
which you should read before adopting.

On permissions. The allowlist grants Bash(*) — every shell command,
unprompted. That is a deliberate trade for an autonomous single-operator machine,
not an oversight, and it is the setting to change first if you adopt this. It
used to sit above forty specific Bash(...) entries that it already subsumed;
those are gone, because a list that grants nothing reads like the real boundary
and isn't. hooks/on-pre-tool.sh (target-aware refusals, tested by
hooks/test-on-pre-tool.sh) and autoMode.soft_deny catch common accidents but
are string-matching heuristics, not security boundaries. Sandbox and permission
policy are the real controls; narrow Bash(*) if you want stronger Claude
isolation. wezterm/families.example.json is an
example; copy it to ~/.claude/fleet/families.json and use absolute paths (the
cwd is handed to WezTerm verbatim — no ~ or $HOME expansion).

Portability boundary

This installation makes instruction and skill discovery reproducible across
Claude, Codex, and Grok. Project files, branches, worktrees, task plans, and
commits are the durable state shared between them; each harness keeps and
resumes its own sessions. This repository does not translate transcripts or
try to make one harness resume another's session.

Shared workflow skills use semantic operations—apply another skill, yield for a
decision, delegate a role, and run a long-lived tool—plus the neutral source
alias. Hooks, permissions, session stores, exact reviewer tool grants, and UI
preferences remain native to each harness. Add a vendor adapter only where a
demonstrated incompatibility requires one; do not add a workflow runtime,
duplicate skill bodies, or per-harness worktree manager.

Not in this repo

Some things are deliberately kept out of git and stay on the machine: Claude
Code's own runtime state (.claude.json, transcripts, caches), anything
credential-shaped, and a couple of personal assets. .gitignore covers what
exists today; hooks/pre-commit is the backstop for what shows up tomorrow — it
refuses to stage transcripts, credential-shaped paths, runtime-state
directories, and content matching known key formats.

If you clone this, note that skills/kauffj-voice and skills/writing encode
one person's voice and writing process. They are here as worked examples of
encoding a preference into a skill, not as something to use as-is.

License

MIT — see LICENSE. Take what is useful; attribution appreciated but
the license is the agreement.