Dotfiles for AI coding agents. One repo syncs instructions, skills, secrets, and autonomous loops across every machine.

ctrl is the structure — instructions, skills, rules, secrets, context. shft is the autonomous loop — it picks issues, implements, commits, repeats.

Every developer using Claude Code or Copilot hits the same walls. Context degrades mid-task — the agent repeats itself, compaction loses nuance, quality drops. Instructions drift between your laptop and VPS. Secrets leak into agent context. Irrelevant rules load for every project regardless of stack.

ctrl+shft fixes all four. Clone it once, bootstrap.sh symlinks your instructions, skills, agents, and rules into ~/.claude/, and git pull updates every machine. detect-context.sh loads only the rules that match your current stack. Secrets split into three tiers — config the agent can see, credentials that exist only inside a child process and vanish when it exits (run-with-secrets.sh), and AFK iteration tokens (short-lived GitHub App installation tokens) minted per loop. When context gets high, the agent persists its plan to working/ so a fresh conversation continues exactly where the old one left off.

Source of truth: ~/dotfiles/ is canonical. ~/.claude/, ~/.copilot/, and ~/.agents/ are consumer targets populated from dotfiles (symlinked where possible, Windows fallback copy when needed). Make all edits in ~/dotfiles/ only. See docs/ARCHITECTURE.md for the internal system map.

# Fork at github.com/arndvs/ctrlshft/fork, then:
git clone https://github.com/YOUR_USERNAME/ctrlshft.git ~/dotfiles
bash ~/dotfiles/bin/bootstrap.sh   # or after install: ctrl bootstrap

Bootstrap is idempotent and cross-platform. It symlinks ~/.claude/CLAUDE.md, ~/.claude/skills/, ~/.claude/agents/, and ~/.claude/rules/, wires shell integration into ~/.bashrc/~/.zshrc, creates secrets/ from templates, installs Python dependencies from skills/_local/requirements.txt into secrets/.venv (including PyJWT for AFK GitHub App token minting), and adds supply chain protection to ~/.npmrc and uv.toml. Full details in the Installation section.

/grill-me       → Interrogate you about a feature until shared understanding
/write-a-prd    → Explore codebase, interview, write PRD, submit as GitHub issue
/architect      → Plan implementation — vertical slices, dependency graphs, acceptance criteria
/prd-to-issues  → Break the PRD into vertical slices → GitHub issues (AFK vs HITL labeled)
/do-work        → Understand → Plan → Implement → Validate → Commit (loops)
shft            → Pick issues from the backlog, implement in a Docker sandbox, commit, repeat

graph TD
    A[Human Intent] --> B["/grill-me — interrogation"]
    B --> C["/write-a-prd — PRD → GitHub Issue"]
    C --> AR["/architect — vertical slices, dependency graphs"]
    AR --> D["/prd-to-issues — slices → GitHub Issues"]
    D --> E["/do-work — Understand → Plan → Implement → Validate → Commit"]
    E -->|loop| E
    E -->|"context high → persist plan to working/"| H["Fresh conversation picks up @working/plan.md"]
    H --> E
    E --> F["shft — AFK loop consuming GitHub issues backlog"]
    F -->|loop| F
    F --> G["Human QA + /improve-architecture"]
    G -->|new issues| D

Use any skill individually or chain them. The planning pipeline (grill-me → write-a-prd → architect → prd-to-issues → do-work) hands off between stages.

Clone to ~/dotfiles on your laptop, your VPS, anywhere. git pull updates both. That's it.

You edit CLAUDE.base.md (tracked in git). bootstrap.sh generates CLAUDE.md from it by appending @-references to any local instruction files in instructions/_local/. The generated file is symlinked to ~/.claude/ and read by Claude Code at runtime.

detect-context.sh scans your working directory and exports ACTIVE_CONTEXTS. A Next.js project loads Next.js rules. A PHP project loads PHP rules. Nothing leaks between stacks.

VS Code opens a project
  ↓
CLAUDE.md → global.instructions.md (always loaded)
  ↓
detect-context.sh → ACTIVE_CONTEXTS=general,nextjs,node,typescript,sanity,prisma
  ↓
loads matching instructions/*.md
  ↓
rules/ scoped by paths: frontmatter — load only when matching files are touched
  ↓
agents/ available as subagent personas — isolated context, read-only tools
  ↓
skills/ auto-discovered — workflow + your personal _local/ skills

One setting enables the chain: "chat.instructionsFilesLocations": {"~/dotfiles": true} — included in settings.json, applied by sync-settings.sh.

skills/_local/ and instructions/_local/ are gitignored. Drop private or business-specific files there — auto-discovered alongside the public ones, never leave your machine.

skills/
├── do-work/                 ← public, tracked
├── systematic-debugging/    ← public, tracked
└── _local/                  ← GITIGNORED — yours alone
    └── your-skill/SKILL.md

agents/ defines specialized subagents with their own system prompts, tool restrictions, and model preferences. Each runs in an isolated context window — exploration stays out of your main conversation.

Agents come in model variants — choose based on task complexity and cost sensitivity:

All agents use read-only tools (Read, Grep, Glob, Bash) and memory: user for persistent cross-project learnings. Add your own: agents/your-agent.md — auto-discovered. See agents/README.md for the full model selection guide.

Platform limitation: Runtime model injection is not supported. Neither search_subagent nor runSubagent accepts a model parameter per-call. Model selection is static — set via model: frontmatter in agent files, or chat.exploreAgent.defaultModel for VS Code sub-agents. Create variant agent files to benchmark different models on the same task.

rules/ contains convention-enforcement files that load only when the agent touches matching files. Each rule uses paths: YAML frontmatter to scope itself.

Rules without paths: load every session. Add your own: rules/your-rule.md — auto-discovered. See rules/README.md for the full inventory.

Instructions are organized so the always-on payload stays small and conditional knowledge only loads when needed:

Re-shelve aggressively: if a rule applies only to .tsx files, it belongs in rules/, not global.instructions.md. See instructions/README.md for the full instruction inventory and loading conditions.

Three tiers. Agents see config, never credentials — and AFK loops use AFK iteration tokens instead of long-lived auth tokens.

run-with-secrets.sh injects credentials into a child process only — they vanish when it exits. Claude Code deny rules block env, printenv, cat secrets/*, and echo $*KEY* at the agent level. Agents can't accidentally inherit what they can't see. See secrets/README.md for the full tier model.

For AFK runs, credentials should rotate between Docker iterations:

• Mint an AFK iteration token (short-lived GitHub App installation token) for each loop
• Inject the token only for that iteration's process
• Expire naturally (and fail closed on mint failure)
• Do not allow PAT fallback in AFK mode

This closes the most common leakage path: one long-lived credential reused across many autonomous runs.

After clone + bootstrap, this is the exact secure AFK setup path:

1. Create a GitHub App at https://github.com/settings/apps/new.

   • Name: e.g. ctrl-shft-bot
   • Homepage URL: your own GitHub dotfiles repository URL (e.g. https://github.com/<you>/dotfiles)
   • Webhook: disable for now (not required for this flow)
   • Repository permissions (minimum):
     • Contents: Read & Write
     • Issues: Read & Write
     • Pull requests: Read & Write
     • Workflows: Read & Write (only if AFK needs to edit .github/workflows/*)
   • Installation target: only your account/org that owns the repo

2. In the App settings page, click Generate a private key and download the .pem file.

3. Install the App on the repo/fork AFK will work on:

   • Open your app page (e.g. https://github.com/settings/apps/ctrl-shft-bot)
   • Click Install App
   • Choose account/org, then Only select repositories, then target repo, then Install

4. Capture your installation ID from the redirect URL after install:

   • URL format: https://github.com/settings/installations/<id>
   • The numeric trailing segment is GITHUB_APP_INSTALLATION_ID

5. Base64 encode the private key to one line:

   • Linux / Git Bash: base64 -w 0 ~/Downloads/your-app-key.pem
   • macOS: base64 < ~/Downloads/your-app-key.pem | tr -d '\n'
   • PowerShell: [Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\\Downloads\\your-app-key.pem"))

6. Fill ~/dotfiles/secrets/.env.secrets with:

   • GITHUB_APP_ID
   • GITHUB_APP_INSTALLATION_ID
   • GITHUB_APP_PRIVATE_KEY_B64

7. Run ctrl check --afk and fix any hard-fail messages.

8. Run token-safe mint verification (prints status/expiry/length, not the raw token):

   ctrl verify-token

   Expected shape:

   ================================================================
   GitHub App Token Smoke Test (safe output)
   ================================================================
     ✓ mint_success=yes
       expires_at=2026-04-14T23:58:47Z
       token_len=40
   ================================================================
   

9. Start AFK with one iteration (shft afk 1), then scale iterations once stable.

Windows note (important): On some Windows setups, python3 resolves to a Microsoft Store alias and fails. AFK scripts now prefer secrets/.venv Python automatically. If you hit Python launch/dependency errors, rerun bash ~/dotfiles/bin/bootstrap.sh to rebuild the venv and retry.

If PAT variables are present in AFK mode, treat that as a hard configuration error and remediate before running.

If mint_github_app_token.py reports missing PyJWT or requests, re-run ctrl bootstrap (or bash ~/dotfiles/bin/bootstrap.sh) to refresh secrets/.venv packages.

If a raw token is ever printed to terminal/chat/logs, treat that as an exposure event and rotate immediately:

1. Open https://github.com/settings/apps/ctrl-shft-bot
2. Regenerate (or delete + generate) a new private key
3. Download new .pem
4. Re-encode: base64 -w 0 ~/Downloads/your-new-key.pem
5. Update GITHUB_APP_PRIVATE_KEY_B64 in secrets/.env.secrets
6. Re-run the token-safe mint verification command above

Every skill's description is loaded into the agent's system prompt at session start. The agent reads a skill's full SKILL.md when it detects a matching situation. Skills marked ⚡ have broad descriptions that match common task patterns — the agent loads them automatically without you asking. The rest have narrow descriptions and fire only when you invoke them by name or via /slash-command.

The benefit: ⚡ skills act as passive guardrails. You don't remember to say "use the debugging skill" — the agent recognizes an error and loads the root-cause-first investigation protocol on its own. Same rigorous process every time, without you thinking about it.

Add your own: skills/_local/your-skill/SKILL.md — auto-discovered, gitignored. See skills/README.md for the full catalog with trigger phrases.

Thin launchers in commands/ that load a skill with your arguments. Type the command in chat — the agent loads the full skill protocol automatically.

Add your own: commands/your-command.md — auto-discovered. Each file is a prompt template with $ARGUMENTS passthrough. See commands/README.md for the full command reference.

Four behavioral principles baked into global.instructions.md, derived from Andrej Karpathy's observations on LLM coding pitfalls. These address the most expensive failure modes: building the wrong thing, overengineering, drive-by refactoring, and vague success criteria.

Don't assume. Don't hide confusion. Surface tradeoffs.

LLMs silently pick an interpretation and run with it. These rules force explicit reasoning:

• Stop when confused — Name what's unclear and ask. Never pick an interpretation silently
• Present multiple interpretations — If ambiguity exists, list options and ask which one before implementing
• Push back when simpler exists — If a simpler approach works, say so — even if the user asked for the complex version
• State assumptions explicitly — If uncertain, ask follow-up questions. Think "What's wrong with this plan?"

Minimum code that solves the problem. Nothing speculative.

Combat the tendency toward overengineering:

• No features beyond what was asked
• No abstractions for single-use code
• No "flexibility" or "configurability" that wasn't requested
• No error handling for impossible scenarios
• If 200 lines could be 50, rewrite it

The test: Would a senior engineer say this is overcomplicated? If yes, simplify.

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Match existing style exactly — even if you'd write it differently. No formatting, naming, or structural changes outside the task
• Don't refactor what isn't broken — if you notice unrelated problems, mention them — don't fix them
• Mention unrelated dead code, don't delete it — only remove imports/variables/functions that YOUR changes made unused
• Don't "improve" adjacent code, comments, or formatting

The test: Every changed line should trace directly to the user's request.

Define success criteria. Loop until verified.

Transform imperative tasks into verifiable goals:

For multi-step tasks, state a brief plan with verification at each step. Strong success criteria let the agent loop independently. Weak criteria ("make it work") require constant clarification.

ctrl extends this with dedicated skills: tdd (red-green-refactor), systematic-debugging (root-cause-first investigation), and do-work (auto-detects feedback loops and validates before committing).

These principles are working if you see:

• Fewer unnecessary changes in diffs — only requested changes appear
• Fewer rewrites due to overcomplication — code is simple the first time
• Clarifying questions come before implementation — not after mistakes
• Clean, minimal commits — no drive-by refactoring or "improvements"

Tradeoff: These principles bias toward caution over speed. For trivial tasks (typo fixes, obvious one-liners), the agent uses judgment — not every change needs the full rigor.

Claude Code lifecycle hooks — shell scripts that fire on tool use and session events. Bootstrap symlinks hooks/ → ~/.claude/hooks/ and merges configuration from settings-hooks.json into ~/.claude/settings.json.

Hooks communicate via exit codes: 0 = allow, 2 = block. See hooks/README.md for full documentation, customization, and the experiments/ directory for in-progress prototypes.

ctrl is the structure — instructions, skills, rules, secrets, context. shft is the autonomous loop — it picks issues, implements, commits, repeats. ctrl+shft — you define the rules, shft executes them.

shft is not a framework. It's a bash loop that runs Claude against your GitHub issues backlog — sandboxed in Docker for Away From Keyboard (AFK) mode, direct on host for Human In The Loop (HITL). See shft/README.md for the full command reference.

AFK mode: Claude picks a task, implements it, commits, closes the issue, picks the next one. Exits when the backlog is empty (<promise>NO MORE TASKS</promise>). You review PRs async.

1. Critical bugfixes — blockers first
2. Dev infrastructure — tests, types, scripts before features
3. Tracer bullets — small end-to-end slices that validate approach
4. Polish and quick wins
5. Refactors

--dangerously-skip-permissions needs a cage. Docker isolates Claude in a micro-VM. It can run commands, write files, use git — but it can't reach your host filesystem.

# srt (Anthropic Sandbox Runtime) manages Docker containers
srt claude .

• Claude Max subscription
• Docker Desktop installed
• jq installed
• srt (Anthropic Sandbox Runtime) installed
• shft/once.sh, shft/afk.sh, shft/prompt.md in place
• GitHub App credentials configured in secrets/.env.secrets (GITHUB_APP_ID, GITHUB_APP_INSTALLATION_ID, GITHUB_APP_PRIVATE_KEY_B64)
• Deny rules validated in sandbox
• 5–10 well-formed GitHub issues ready
• Start HITL → graduate to AFK (1 iteration) → scale up

After bootstrap, two commands are available system-wide. ctrl manages your environment, shft manages your work queue. Both are symlinked to ~/.local/bin/ by bootstrap. See bin/README.md for the full script inventory.

ctrl help     # infrastructure commands
shft help     # autonomous execution commands

~/dotfiles/
├── CLAUDE.base.md                   ← edit this — bootstrap generates CLAUDE.md from it
├── CLAUDE.md                        ← GENERATED (gitignored)
├── CHANGELOG.md                     ← release history
├── CONTRIBUTING.md                  ← contribution guide
├── global.instructions.md           ← universal rules, always loaded
├── package.json                     ← optional deps (better-sqlite3 for HUD persistence)
├── settings.json                    ← managed VS Code settings
├── .env.agent.example               ← template for non-sensitive config
├── .env.citation.example            ← template for citation skill config
├── .env.secrets.example             ← template for API keys and tokens
├── .gitattributes                   ← LF line ending enforcement
├── instructions/
│   ├── nextjs.instructions.md
│   ├── php.instructions.md
│   ├── sanity.instructions.md
│   ├── sentry.instructions.md
│   ├── google-docs.instructions.md
│   ├── css.instructions.md
│   ├── handoff.instructions.md      ← cross-conversation persistence protocol
│   └── _local/                      ← GITIGNORED — your private instructions
├── commands/
│   ├── audit.md                     /audit → codebase-audit skill
│   ├── document.md                  /document → document skill
│   ├── explore.md                   /explore → explore skill
│   ├── plan.md                      /plan → architect skill
│   ├── review.md                    /review → code-review skill
│   ├── test.md                      /test → tdd skill
│   └── work.md                      /work → do-work skill
├── agents/
│   ├── README.md                    model selection guide + agent docs
│   ├── code-reviewer.md             subagent: bugs, correctness, security (sonnet)
│   ├── code-reviewer-opus.md        subagent: high-stakes reviews (opus)
│   ├── researcher.md                subagent: deep codebase exploration (sonnet)
│   ├── researcher-opus.md           subagent: complex architecture analysis (opus)
│   ├── researcher-haiku.md          subagent: fast bulk scanning (haiku)
│   └── security-auditor.md          subagent: OWASP, secrets, config (sonnet)
├── rules/
│   ├── test-conventions.md          scoped to tests and service code
│   ├── migration-safety.md          scoped to **/migrations/**
│   ├── env-security.md              scoped to **/.env*, **/secrets/**
│   └── terminal-workarounds.md      scoped to terminal sessions
├── hooks/
│   ├── README.md                    hook documentation
│   ├── settings-hooks.json          hook configuration for Claude Code
│   ├── compaction-guard.sh          blocks auto-compaction, enforces handoff
│   ├── context-warning.sh           graduated warnings at 40/70% context
│   ├── format-check.sh             auto-formats modified files on stop
│   ├── migration-guard.sh           blocks unsafe migration commands
│   ├── secret-guard.sh              blocks credential exposure in agent output
│   ├── typecheck.sh                 runs tsc --noEmit before stop
│   └── experiments/                 experimental hook prototypes
├── skills/
│   ├── do-work/
│   ├── grill-me/
│   ├── write-a-prd/
│   ├── prd-to-issues/
│   ├── architect/
│   ├── skill-scaffolder/
│   ├── explore/
│   ├── research/
│   ├── codebase-audit/
│   ├── improve-architecture/
│   ├── tdd/
│   ├── systematic-debugging/
│   ├── atomic-commits/
│   ├── code-review/
│   ├── document/
│   ├── compliance-audit/
│   ├── stress-test/
│   ├── sanity-best-practices/
│   └── _local/                      ← GITIGNORED — your private skills
├── clients/
│   ├── README.md                    per-client instruction isolation guide
│   └── _template/                   scaffolding for new client projects
├── shft/
│   ├── shft                         CLI entry point — autonomous execution
│   ├── afk.sh                       AFK autonomous loop
│   ├── once.sh                      HITL single-run
│   ├── _build_prompt.sh             prompt assembly for shft runs
│   └── prompt.md                    shared agent prompt
├── bin/
│   ├── ctrl                         CLI entry point — infrastructure management
│   ├── _lib.sh                      shared shell library
│   ├── _adopt.sh                    bootstrap --adopt migration helper
│   ├── bootstrap.sh                 one-command setup, idempotent
│   ├── agent-shell.sh               secrets-free shell for agent sessions
│   ├── sync-settings.sh             deep-merge VS Code settings
│   ├── load-secrets.sh              sources .env.agent into shell
│   ├── run-with-secrets.sh          process-scoped secret injection
│   ├── detect-context.sh            exports ACTIVE_CONTEXTS
│   ├── detect-client.sh             per-client context detection
│   ├── new-client.sh                scaffold new client instruction set
│   ├── migrate.sh                   safe migration from manual setup
│   ├── uninstall.sh                 clean removal of all symlinks + shell integration
│   ├── validate-env.sh              env + hardening validation
│   ├── validate-symlinks.sh         verify bootstrap symlinks
│   ├── mint_github_app_token.py     AFK token minting
│   ├── verify-github-app-token.sh   safe token verification
│   ├── hud-daemon.js          HUD HTTP server
│   ├── start-hud.sh           daemon lifecycle (start/stop/status/restart)
│   └── write-hud-state.sh     non-blocking compliance event emitter
├── hud/                       ← HUD UI
│   ├── README.md                    HUD architecture + API reference
│   └── index.html
├── site/                            ← landing page (ctrlshft.dev)
│   ├── index.html
│   ├── CNAME
│   └── assets/
├── docs/
│   ├── adr/                         architecture decision records
│   ├── observability-benchmarking-plan.md
│   └── readme-site-deep-audit.md
├── working/                         ← GITIGNORED — cross-conversation plans
└── secrets/                         ← GITIGNORED
    ├── .env.agent
    ├── .env.secrets
    └── .venv/

Before you install: Bootstrap is mostly idempotent but touches several dotfiles:

• ~/.claude/CLAUDE.md — replaced with a symlink (or overwritten on Windows). Back up if you have a custom one.
• ~/.claude/skills/ — symlinked if absent or a stale link. Existing real directories are left alone (manual merge message shown).
• ~/.claude/agents/ — symlinked if absent or a stale link. Same behavior as skills/.
• ~/.claude/rules/ — symlinked if absent or a stale link. Same behavior as skills/.
• ~/.claude/commands/ — symlinked if absent or a stale link. Slash command wrappers.
• ~/.claude/hooks/ — symlinked if absent or a stale link. Lifecycle hook scripts.
• ~/.claude/settings.json — hook configuration merged (requires jq). Existing settings preserved.
• ~/.bashrc / ~/.zshrc — appends shell integration (load-secrets + context detection). Idempotent on re-runs.
• ~/.npmrc — appends min-release-age=7 for supply chain protection.
• ~/.config/uv/uv.toml — adds exclude-newer date for supply chain protection.

Not run by bootstrap: sync-settings.sh (VS Code settings merge) is a separate manual step. Run with --dry-run first to preview changes.

# Fork at github.com/arndvs/ctrlshft/fork, then:
git clone https://github.com/YOUR_USERNAME/ctrlshft.git ~/dotfiles
bash ~/dotfiles/bin/bootstrap.sh

$EDITOR ~/dotfiles/secrets/.env.agent       # non-sensitive config
$EDITOR ~/dotfiles/secrets/.env.secrets     # API keys and tokens
source ~/.bashrc                            # adds ctrl/shft to PATH
ctrl sync-settings                          # merge VS Code settings

# Fork at github.com/arndvs/ctrlshft/fork, then:
git clone https://github.com/YOUR_USERNAME/ctrlshft.git ~/dotfiles
bash ~/dotfiles/bin/bootstrap.sh
$EDITOR ~/dotfiles/secrets/.env.agent
$EDITOR ~/dotfiles/secrets/.env.secrets
source ~/.bashrc

# 1. Fork at github.com/arndvs/ctrlshft/fork, then clone
git clone https://github.com/YOUR_USERNAME/ctrlshft.git ~/dotfiles

# 2. Generate CLAUDE.md and symlink
bash ~/dotfiles/bin/bootstrap.sh   # or manually:
mkdir -p ~/.claude
ln -sf ~/dotfiles/CLAUDE.md ~/.claude/CLAUDE.md
ln -sf ~/dotfiles/skills ~/.claude/skills
ln -sf ~/dotfiles/agents ~/.claude/agents
ln -sf ~/dotfiles/rules ~/.claude/rules
ln -sf ~/dotfiles/commands ~/.claude/commands
ln -sf ~/dotfiles/hooks ~/.claude/hooks

# 3. Secrets
cp ~/dotfiles/.env.agent.example ~/dotfiles/secrets/.env.agent
cp ~/dotfiles/.env.secrets.example ~/dotfiles/secrets/.env.secrets

# 4. Shell integration — add to ~/.bashrc
[[ -f ~/dotfiles/bin/load-secrets.sh ]] && source ~/dotfiles/bin/load-secrets.sh
_load_context() { [[ -f ~/dotfiles/bin/detect-context.sh ]] && source ~/dotfiles/bin/detect-context.sh > /dev/null 2>&1; }
cd() { builtin cd "$@" && _load_context; }
_load_context

# 5. VS Code settings
ctrl sync-settings

cd ~/dotfiles && git pull
ctrl bootstrap                        # re-validates, fixes stale symlinks
ctrl sync-settings                    # optional: merge VS Code settings
source ~/.bashrc

Guardrails are enforced in CI by .github/workflows/integrity.yml.

It validates:

• source-of-truth language exists in global.instructions.md and CLAUDE.base.md
• deprecated disable-model-invocation flags are absent from skills/**/SKILL.md
• static integrity checks pass via bash bin/validate-symlinks.sh --ci

Run local checks before opening a PR:

ctrl check               # or: bash ~/dotfiles/bin/validate-env.sh && bash ~/dotfiles/bin/validate-symlinks.sh --ci

Notes:

• Windows fallback copies are allowed when content matches the ~/dotfiles source.
• CI is stricter for deprecated skill flags; local validate-symlinks.sh reports them as warnings.

Contribution infrastructure is now in-repo:

• Guide: CONTRIBUTING.md
• Changelog: CHANGELOG.md
• Issue templates: .github/ISSUE_TEMPLATE/
• PR template: .github/pull_request_template.md
• Skill lint workflow: .github/workflows/skill-lint.yml

When your PR touches skills/**, the Skill lint workflow validates skill file structure automatically.

Project contributors: arndvs/ctrlshft/graphs/contributors

The HUD is a live display that shows what your agent is actually doing — which rules loaded, which skills fired, which projects are being touched, and whether compliance checks pass or fail. It runs locally at localhost:7823 and updates in real-time via WebSocket.

ctrl hud
# Visit http://localhost:7823

Alternatively: bash ~/dotfiles/bin/start-hud.sh

The HUD has three layers:

1. Event producers — hooks (hud-reads.sh, hud-session.sh), detect-context.sh, compliance-audit skill, and write-hud-state.sh (sourceable shell functions)
2. Daemon — bin/hud-daemon.js (~880 lines, zero required npm dependencies). Listens on named pipe (< 1ms), HTTP POST, and JSONL file watcher. Optional SQLite persistence via better-sqlite3
3. Frontend — hud/index.html (single-file). Connects via WebSocket (ws://localhost:7822) for real-time updates, falls back to HTTP polling

Cross-project tracking works automatically. When the agent reads files outside ~/dotfiles/, the reads hook walks up the directory tree to find the .git root, extracts the project name, and routes events to the correct project tab.

Port defaults to 7823. Override with HUD_PORT=8080.

Alternatively use the scripts directly: bash ~/dotfiles/bin/start-hud.sh [stop|status|restart]

cd ~/dotfiles && npm install better-sqlite3

Without it, the daemon uses in-memory buffers + JSONL fallback. History resets on restart.

See hud/README.md for the full API reference, event types, auto-start configuration (launchd/systemd), and data persistence details.

Status: HUD shipped — see docs/observability-benchmarking-plan.md for the tracked implementation plan.

• Sub-agent model injection is not possible at runtime. Neither search_subagent nor runSubagent accepts a model parameter. Workaround: model-variant agent files.
• Hallucination detection requires human scoring. Automated proxy signals (test failures, reverts) augment but cannot replace human judgment.
• OTEL schema is undocumented. Need to enable it and inspect raw spans before building on it.

• VS Code (stable or Insiders)
• GitHub Copilot (optional — ctrl works with Claude Code alone)
• Git Bash (Windows) or bash (Linux/macOS)
• Python 3.10+
• jq — JSON processor (required by shft/afk.sh token parsing)
  • Windows: winget install jqlang.jq or choco install jq
  • macOS: brew install jq
  • Linux: sudo apt install jq
• srt — Anthropic Sandbox Runtime (used by shft/afk.sh)
  • Install: npm install -g @anthropic-ai/sandbox-runtime
• Docker Desktop (for shft)

Naming: The GitHub repo is arndvs/ctrlshft but the on-disk path is ~/dotfiles — hardcoded across 40+ references. Clone it to ~/dotfiles and leave it there.