Skip to content

About

No description, website, or topics provided.

Resources

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

claude-code-config

Claude Code macOS Linux Windows

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 you get

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.

Quick start

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 needed

Setup 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.env
Add-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 subagents

Getting started walks through the same steps with the output to expect at each one.

Platform support

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.

Highlights

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 account

Session 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 and skills

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

Documentation

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

Development

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 them

Shell 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.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages