{
  "markdown": "# Claude Code Configuration\n\nPersonal configuration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code): agent guidelines, slash commands, subagents, language-specific skills, plugins, a Zig statusline, and a settings baseline. Designed to be usable as a standalone repo or as a submodule of a larger dotfiles tree.\n\n## Quick Start\n\nClone the repo anywhere, then run the installer to symlink runtime assets into `~/.claude/`:\n\n```bash\ngit clone https://github.com/alleneubank/claude-code.git ~/code/claude-code\ncd ~/code/claude-code\n./install.sh             # apply symlinks\n./install.sh --check     # report drift without changing anything\n```\n\nThe installer is idempotent. It links:\n\n- `CLAUDE.md` → `~/.claude/CLAUDE.md` (agent guidelines)\n- `commands/` → `~/.claude/commands/` (slash commands)\n- `agents/` → `~/.claude/agents/` (subagents)\n- `.claude/skills/` → `~/.claude/skills/` (best-practices skills)\n- `codex.json` → `~/.claude/codex.json` (Codex CLI config for the `codex-reviewer` plugin)\n\nSettings, statusline binary, and plugins are opt-in — see the sections below.\n\n## Repository Layout\n\n```\nclaude-code/\n├── CLAUDE.md                    # Agent guidelines (linked into ~/.claude/CLAUDE.md)\n├── codex.json                   # Codex CLI defaults (linked into ~/.claude/codex.json)\n├── install.sh                   # Idempotent symlink installer\n├── commands/                    # Slash commands\n├── agents/                      # Subagents\n├── .claude/skills/              # Best-practices skills (auto-load by file context)\n├── .claude-plugin/              # Marketplace manifest for the bundled plugins\n├── plugins/                     # Source for plugins published via marketplace.json\n│   ├── codex-reviewer/          # Codex CLI review gate\n│   └── ralph-reviewed/          # Iterative loop with Codex review\n├── codex-overrides/skills/      # Codex-only skill overrides applied during sync\n├── settings/settings.json       # Settings baseline (copy or merge into ~/.claude/settings.json)\n├── statusline/                  # Zig statusline (build separately, see below)\n├── hooks/direnv-bash-env        # BASH_ENV shim that loads direnv on subshell cd\n├── scripts/                     # Usage tracking, codex sync, plugin version checks\n└── analytics/                   # Submodule: claude-code-analytics (transcript analyzer)\n```\n\n## Commands\n\nInvoked with `/<name>` in Claude Code. Sources live in `commands/`.\n\n| Command | Description |\n|---------|-------------|\n| `/commit` | Stage, draft, and create a conventional git commit from the current diff |\n| `/fix-issue <id>` | Find and fix an issue end-to-end with tests and a PR description |\n| `/greenline` | Tilt bootstrap then iterative e2e baseline improvement with categorized fixes |\n| `/handoff` | Generate a self-contained handoff prompt for another agent (writes to `~/.handoffs/`) |\n| `/rewrite-history` | Rewrite the current branch with a clean narrative commit history |\n| `/specout` | Interview-driven workflow to fill gaps in a `SPEC.md` |\n| `/triage` | Interactive Linear issue triage with codebase verification |\n\n## Subagents\n\nCustom subagents in `agents/`. Claude Code delegates automatically when their description matches the task.\n\n| Agent | Purpose |\n|-------|---------|\n| `code-reviewer` | Reviews changes for quality, security, and project conventions |\n| `debugger` | Investigates failures through root cause analysis |\n| `refactorer` | Restructures code with clean breaks and complete migrations |\n| `test-writer` | Writes tests that verify correctness without gaming assertions |\n\n## Skills\n\nBest-practices skills in `.claude/skills/` are auto-loaded when the file context matches their triggers. The full set:\n\n| Skill | Use when |\n|-------|----------|\n| `atlas-best-practices` | Editing `atlas.hcl`, schema HCL/SQL, or planning Atlas migrations |\n| `axe-ios-simulator` | Driving the iOS Simulator via AXe (screenshots, accessibility, automation) |\n| `brief-best-practices` | Creating, reviewing, or updating `BRIEF.md` (the quality law for a surface) |\n| `canton-network-repos` | Working with Canton Network participants, Daml, or Splice |\n| `e2e` | Running, debugging, or fixing e2e tests |\n| `electrobun-best-practices` | Building Electrobun desktop apps |\n| `git-best-practices` | Commits, branches, PRs, rewriting history |\n| `git-rebase-sync` | Rebasing a feature branch onto its base |\n| `git-worktree-tidy` | Pruning stale local branches and worktrees |\n| `go-best-practices` | Reading or writing `.go` files |\n| `improve` | Surfacing concrete improvements after a task |\n| `nix-best-practices` | Editing flakes, overlays, `shell.nix`, `flake.nix` |\n| `op-cli` | Reading secrets from 1Password via `op` |\n| `orbstack-best-practices` | OrbStack Linux VMs and Docker on macOS |\n| `playwright-best-practices` | Writing or modifying Playwright tests |\n| `python-best-practices` | Reading or writing Python files |\n| `react-best-practices` | Reading or writing React components |\n| `spec-best-practices` | Creating, reviewing, or updating `SPEC.md` |\n| `tamagui-best-practices` | Working in Tamagui projects |\n| `testing-best-practices` | Designing tests and planning test strategy |\n| `tilt` | Reading Tilt status, logs, working with Tiltfiles |\n| `tiltup` | Bootstrapping Tilt to a healthy state |\n| `typescript-best-practices` | Reading or writing TypeScript / JavaScript files |\n| `web-fetch` | Fetching web content as clean markdown |\n| `zig-best-practices` | Reading or writing Zig files |\n| `zmx` | Managing long-lived dev processes via `zmx` |\n\n## Plugins\n\nThis repo also doubles as a Claude Code plugin marketplace via `.claude-plugin/marketplace.json`. Two plugins ship from it:\n\n| Plugin | Description |\n|--------|-------------|\n| `ralph-reviewed` | Iterative Ralph loop with a Codex CLI review gate at completion |\n| `codex-reviewer` | Standalone Codex-powered code review gate |\n\n### Install as a marketplace\n\n```bash\n# Inside Claude Code:\n/plugin marketplace add alleneubank/claude-code\n/plugin install ralph-reviewed@0xbigboss-plugins\n/plugin install codex-reviewer@0xbigboss-plugins\n```\n\nOr install from a local checkout:\n\n```bash\n/plugin marketplace add ~/code/claude-code\n```\n\nBoth plugins read `~/.claude/codex.json` for sandbox/approval/timeout settings — `install.sh` puts a default copy there. See `plugins/ralph-reviewed/README.md` for the full schema.\n\n## Settings Baseline\n\n`settings/settings.json` is an opinionated baseline you can adopt as-is or use as a reference:\n\n- `permissions.allow` pre-approves common read-only and safe-write Bash patterns (git, npm/bun/yarn, zig, go, tilt, kubectl, docker, gh) plus a few skills.\n- `extraKnownMarketplaces` declares plugin marketplaces; `enabledPlugins` controls which are turned on.\n- `statusLine.command` invokes the Zig statusline binary (see below).\n- `env.BASH_ENV` points at `hooks/direnv-bash-env` so subshells reload direnv on `cd`.\n\nThis file ships with author-specific marketplace pointers (e.g. private Send/Canton repos) and a hard-coded `BASH_ENV` path. If you adopt it, edit those fields to match your machine. The simplest path is to copy it once and treat `~/.claude/settings.json` as yours:\n\n```bash\ncp settings/settings.json ~/.claude/settings.json\n```\n\nThe author personally generates `~/.claude/settings.json` via a private merge helper in the surrounding dotfiles tree (baseline + `~/.claude/settings.local.json` overrides). That helper is not required to use this repo — direct copy works fine.\n\n## Statusline\n\nA small Zig statusline lives in `statusline/`. It reads JSON on stdin and prints one formatted status line.\n\n```bash\ncd statusline\nzig build -Doptimize=ReleaseFast\n# binary lands at statusline/zig-out/bin/statusline\n```\n\nPoint Claude Code at it by setting `statusLine.command` in `~/.claude/settings.json` (the baseline already does this). Minimum Zig: `0.16.0`. See `statusline/CLAUDE.md` and `statusline/SPEC.md` for build, runtime contract, and design notes.\n\n## Scripts\n\n`scripts/` contains optional utilities:\n\n| Script | Purpose |\n|--------|---------|\n| `setup-usage-tracking.py` | Writes hook overrides into `~/.claude/settings.local.json` to log every session/tool/command |\n| `usage-tracker.py` | The hook handler that records events to SQLite + JSONL |\n| `analyze-usage.py` | Summaries, time-windowed reports, exports |\n| `usage-dashboard.py` | Live terminal dashboard over the SQLite store |\n| `sync-codex.sh` | Mirrors `commands/` + `.claude/skills/` into `~/.codex/` (prompts + skills), applying `codex-overrides/` on top |\n| `check-plugin-versions.sh` | Pre-commit guardrail: plugin source changes must bump `plugin.json` and `marketplace.json` versions in lockstep |\n| `install-symlinks.sh` | Older partial symlinker (kept for compatibility; `install.sh` is the canonical entrypoint) |\n\nSee `scripts/README.md` for the usage-tracking specifics.\n\n### Codex sync (optional)\n\nIf you also use the Codex CLI and want the same skills/commands available there:\n\n```bash\nscripts/sync-codex.sh --check   # report drift (exit 0 clean, 2 drift, 1 error)\nscripts/sync-codex.sh           # apply\n```\n\nCodex skill resolution order during sync:\n1. User skills from `.claude/skills/`\n2. Plugin skills (with selective drops per `scripts/sync-codex.skill-policy.tsv`)\n3. Codex-only overrides from `codex-overrides/skills/` (win on name collision)\n\n## Analytics\n\n`analytics/` is a [submodule](https://github.com/0xbigboss/claude-code-analytics) that analyzes Claude Code transcripts (skill usage, token consumption, tool patterns).\n\n```bash\ngit submodule update --init analytics\ncd analytics && uv sync\nuv run cc-analytics skills\n```\n\n## Instruction Source of Truth\n\n- Shared agent guidelines live in `CLAUDE.md` at the repo root. The installer links this into `~/.claude/CLAUDE.md`.\n- Personal local notes belong in `~/.claude/CLAUDE.local.md` (or this repo's `CLAUDE.local.md`, which is gitignored). Do not move local-only content into the tracked `CLAUDE.md` — it is meant to be shareable.\n\n## Relationship to a Larger Dotfiles Tree\n\nThe author keeps this repo as a submodule of a private dotfiles tree. When present, that tree's `codex/codex.json` is preferred by `install.sh` over the in-repo sample, and a private `claude-bootstrap` / `claude-settings-merge` pair manages additional symlinks and the settings merge. Neither is required to use this repo standalone — everything in this README assumes no parent tree.\n\n## Author\n\nAllen Eubank ([@alleneubank](https://github.com/alleneubank))\n\n## License\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).\n",
  "bytes": 10596,
  "sha": "da8f9e307b9b69cf2c546fbee4d07ca93c7a1683104a1632d723ba8408c1cad7",
  "repo_slug": "alleneubank/claude-code",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_alleneubank_claude_code_python_best_prac_dedef9fc/readme"
}