A portable Claude Code setup in one Git repository: subagents, skills, hooks, a
status line and a few command-line tools. One script links it into ~/.claude
on macOS, Linux and Windows, so every project on every machine gets the same
configuration, and a git pull updates them all.
opus-5.5 | 32%/72% (39h12m) | 2h13m | 1.6k/68.1k/72.3M | $19.51 | user@example.com
| What it is | |
|---|---|
| Subagents | Experts for Python, Rust, .NET, SQL, dbt, Databricks, MongoDB, design docs and more, most with a standards skill they load |
| Skills | Engineering standards, web search (built-in, Brave, Tavily) and pull request workflows for GitHub, GitLab and Azure DevOps |
| Hooks | Session names, git pull --rebase, IDE diagnostics, a database guardrail, and API key guards for the search servers |
| Status line | Model, 5-hour and weekly usage, reset times, tokens, cost and service status, sized to the terminal |
| MCP search | Brave Search and Tavily, with key pools that rotate when one runs out of quota |
| Full-page reading | /full-search reads JavaScript pages and PDFs through Firecrawl, Tavily or Bright Data, keys and fnox optional |
| Command-line tools | claude-as for several accounts, claude-permissions-audit, claude-secret-guard, claude-proxy, mcp-key-rotate and mcp-env-inject |
| Shell and terminal presets | Optional fish and Ghostty configurations |
When OpenCode is on your PATH, setup installs the same agents for it too.
You need Claude Code, Git and jq,
plus python3 on macOS and Linux. fd and fzf (faster @ file search) are
optional.
1. Clone and install
Fork this repository, so your own changes have somewhere to go, and clone the fork:
git clone https://github.com/<you>/claude-code-config.git
cd claude-code-config
./setup.sh # macOS, Linux, WSL.\setup.ps1 # Windows PowerShell 5.1 or PowerShell 7, no Administrator neededSetup links each agent, skill, hook and script into ~/.claude (or
$CLAUDE_CONFIG_DIR), merges its entries into your settings.json, registers
the search servers and adds bin/ to your PATH. Entries other tools installed
there are left alone. Run it again at any time; ./setup.sh --help lists every
option.
2. Add your search API keys (free tiers: Brave Search, Tavily)
echo 'BRAVE_API_KEY=your-key' >> ~/.claude/mcp-keys.env
echo 'TAVILY_API_KEY=your-key' >> ~/.claude/mcp-keys.envAdd-Content "$HOME\.claude\mcp-keys.env" 'BRAVE_API_KEY=your-key', 'TAVILY_API_KEY=your-key'Without keys everything else works, and /web-search uses Claude's built-in search.
/full-search reads the same file, and also takes keys from the environment or
fnox.
3. Check it
claude mcp list # brave-search and tavily, user scope
claude # then /agents lists the subagentsGetting started walks through the same steps with the output to expect at each one.
| macOS | Linux | Windows | |
|---|---|---|---|
| Installer | setup.sh |
setup.sh |
setup.ps1 |
| Hooks and status line | bash 3.2 or later | bash | Git Bash, from Git for Windows |
| fish and Ghostty presets | Yes | Yes | No |
| Tested in CI | Installer, hooks, status line | Installer, hooks, status line | Installer on x64 and arm64; status line under Git Bash |
On Windows without Developer Mode, folders are linked as junctions and files
are copied, so run setup.ps1 again after each pull. WSL uses setup.sh.
Status line. Usage comes from the plan behind the session's model: Claude's, or the ChatGPT or Muse Code plan when a router runs a GPT or Muse model. Components, progress bars, icons and colors are configurable, and the line shortens to fit narrow terminals. Sessions on the same account show the newest reading any of them has seen. Configure it.
Several accounts. claude-as keeps more than one Claude account signed in
and picks one per session; a session started on one continues on another. A
resume keeps the account the session last ran as, and switching asks first.
claude-as --add you@example.com # once per account and machine
claude-as you@example.com --continue
claude-as -r <session id> # as the account it last ran as
claude-as --move you@example.com # every session in herdr, to that accountSession names. Each session is named once, at its first prompt, as
claude-lap-1012T1412-btree-page-splits-0ed0b890: the name --resume and
Remote Control find it by. Details.
Database guardrail. The sql-expert, databricks-expert and
mongodb-expert agents cannot drop a database or delete without a filter;
databricks-expert is read-only. Levels.
Permission audit. claude-permissions-audit finds allow rules that permit
more than they look like they do, or that saved a password in plain text;
--fix backs the file up and removes them. How to.
Secret guard. claude-secret-guard on adds deny rules that keep Claude's
file tools away from credential files (~/.ssh private keys, ~/.oci,
~/.azure, the fnox key…); off removes exactly those. Off by default.
How to.
Other models. claude-proxy (shortcut clp) starts a local proxy and runs
Claude Code against OpenAI Codex or Antigravity models.
How to.
Subagents (.claude/agents/)
| Agent | For |
|---|---|
code-reviewer-expert |
Reviews a pull request with one expert per language and posts inline comments |
d2-tala-expert |
Architecture diagrams in D2 with the TALA layout engine |
data-scientist |
Machine learning, statistics and feature engineering |
databricks-expert |
Read-only Databricks: queries, Unity Catalog, permission audits, jobs |
dbt-expert |
dbt models, sources, tests and macros |
design-doc-expert |
Design docs, DRI working docs and ADRs |
diataxis-expert |
Documentation organized by the Diátaxis framework |
dotnet-expert |
.NET and C# services and APIs |
internet-researcher |
Multi-source web research with sources compared |
kedro-expert |
Kedro pipelines, catalogs and deployment |
langfuse-expert |
Langfuse traces, prompts and sessions |
linus-torvalds |
Blunt engineering advice, on request |
mongodb-expert |
MongoDB queries, aggregations, schemas and indexes |
pr-manager |
Pull requests on GitHub, GitLab and Azure DevOps |
python-expert |
Typed, production Python |
rust-expert |
Idiomatic Rust |
sonarqube-fixer |
SonarQube and SonarLint issues, read from the server or the IDE |
sql-expert |
SQL across PostgreSQL, MySQL, SQL Server, SQLite, DuckDB and Oracle |
ui-designer |
Components, styling, design systems and accessibility |
Skills (.claude/skills/)
| Skill | For |
|---|---|
web-search, brave-search, tavily-search |
One search with Claude's built-in tool, Brave Search or Tavily |
full-search |
Rendered page text, JavaScript and PDFs included, through Firecrawl, Tavily or Bright Data, and search through Tavily, Firecrawl or Brave; keyless tiers without keys |
internet-research |
Research across Brave Search and Tavily |
pr, pr-writing |
Pull requests and commit messages in Conventional Commits |
pr-operations, pr-review |
Pull request operations and multi-agent review on GitHub, GitLab and Azure DevOps |
mcp-key-rotate |
Quota checks and key rotation for the search servers |
python-standards, rust-standards, dotnet-standards |
Language standards the matching agents load |
sql-standards, mongodb-standards, dbt-standards, databricks-standards, kedro-standards |
Data engineering standards |
design-doc-standards, diataxis-standards, d2-tala-standards |
Writing and diagram standards |
langfuse |
Langfuse observability |
config-hooks in the same folder is a plugin, not a skill: it carries the
stop-nudge hook.
Add an agent · Add a skill · Run skill evals
| Tutorial | Getting started |
| How-to guides | Configure the status line · Use multiple accounts · Sync across machines · Audit permission rules · Guard secret reads · Use the proxy launcher · Add an MCP server · Read full pages · Add an agent · Add a skill · Run skill evals · Configure fish · Configure Ghostty |
| Reference | Configuration · Hooks · Project structure |
| Explanation | Architecture · Design decisions · Testing and portability · Branching strategies |
just install-tools # the toolchain pinned in mise.toml, through mise
just check # the merge gate: lint, format, secret scan, bats, PowerShell
just verify-clean-machine # the tests with an empty HOME and the system bash, as CI runs themShell code targets bash 3.2, the version macOS ships, and avoids GNU-only flags;
Testing and portability lists the guards that enforce it.
Branch from main and open a pull request; changes are squash-merged.
MIT