This tutorial walks you through installing the Claude Code portable configuration on your machine. By the end, every Claude Code session in every project on this machine will have the repository's subagents, skills and hooks.
Time required: 10 minutes
What you will build: A global Claude Code configuration with search integrations, domain-expert agents, and workflow automation hooks -- all synced from a single Git repository.
Before you begin, confirm that you have the following installed:
1. Claude Code
claude --versionYou should see output like:
2.x.x (Claude Code)
If Claude Code is not installed, install it now:
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash
# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
# Or via Homebrew
brew install --cask claude-code2. jq
jq --versionYou should see output like:
jq-1.7.1 (or later)
If jq is not installed, install it now:
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq3. Git
git --versionYou should see output like:
git version 2.53.0 (or later)
Fork the repository on GitHub, so your own changes have somewhere to go, then clone your fork:
git clone https://github.com/<you>/claude-code-config.git
cd claude-code-configYou should see:
Cloning into 'claude-code-config'...
remote: Enumerating objects: ...
Receiving objects: 100% ...
Run the interactive setup script:
./setup.shThe script begins by checking your prerequisites:
Claude Code Config Setup
========================
Repo location: /Users/you/repos/claude-code-config
Checking prerequisites...
✓ jq found
✓ python3 found
...
After the prerequisite check, the script displays the current installation options and presents a menu:
Current installation options:
core (hooks, scripts, commands): always
agents & skills: yes
MCP search servers: brave-search, tavily
agent teams (experimental): yes
proxy launcher PATH: yes
settings.json: merge (preserve existing, add new)
statusline color theme: dark
...
? What would you like to do?
> Proceed with installation
Customize installation
Cancel
Use the arrow keys to highlight Proceed with installation and press Enter.
The script creates symlinks and configures your environment in numbered steps:
Step 1: Installing managed entries...
✓ ~/.claude/hooks: 9 linked
✓ ~/.claude/scripts: 4 linked
✓ ~/.claude/skills: 22 linked
✓ ~/.claude/agents: 19 linked
Step 2: Configuring hooks (user scope)...
✓ IDE diagnostics hook configured
Step 3: Configuring file suggestion (user scope)...
...
Step 4: Configuring statusline (user scope)...
...
Step 5: Configuring statusline config...
...
Step 6: Configuring agent teams...
...
Step 7: Configuring proxy launcher PATH...
...
Step 8: Configuring MCP servers (user scope)...
Adding brave-search MCP server...
✓ brave-search MCP added
Adding tavily MCP server...
✓ tavily MCP added
Step 9: Environment variables
...
========================================
Setup complete!
========================================
Note: If some optional tools are not installed (like
fdorfzf), the script skips those features gracefully. The core installation still completes successfully.
The configuration uses two MCP search servers that require API keys. Get free API keys from these services:
Brave Search (1,000 searches/month free):
- Go to https://api-dashboard.search.brave.com/
- Sign up or log in
- Click Create API Key
- Copy the key
Tavily (1,000 credits/month free):
- Go to https://tavily.com
- Sign up or log in
- Copy your API key from the dashboard
Add both keys to the MCP keys file that the setup script created:
echo 'BRAVE_API_KEY=your-brave-key-here' >> ~/.claude/mcp-keys.env
echo 'TAVILY_API_KEY=your-tavily-key-here' >> ~/.claude/mcp-keys.envReplace your-brave-key-here and your-tavily-key-here with your actual keys.
Verify the file has both keys:
wc -l ~/.claude/mcp-keys.envYou should see:
2 /Users/you/.claude/mcp-keys.env
Confirm the MCP servers are registered:
claude mcp listYou should see both servers listed:
brave-search: npx ... (user)
tavily: npx ... (user)
Open Claude Code in any project directory:
cd claude-code-config
claudeInside the Claude Code session, type:
/agents
You should see every agent in .claude/agents/:
code-reviewer-expert
d2-tala-expert
data-scientist
databricks-expert
dbt-expert
design-doc-expert
diataxis-expert
dotnet-expert
internet-researcher
kedro-expert
langfuse-expert
linus-torvalds
mongodb-expert
pr-manager
python-expert
rust-expert
sonarqube-fixer
sql-expert
ui-designer
In the same Claude Code session, type:
/help
You should see available slash commands including:
/brave-search - Search using Brave Search MCP
/tavily-search - AI-native search using Tavily MCP
/web-search - Quick search using built-in WebSearch
/pr - Create PR/MR with Conventional Commits
/pr-review - Multi-agent PR review
/mcp-key-rotate - Rotate MCP API keys
In the same Claude Code session, run a Brave Search query:
/brave-search Claude Code MCP servers
You should see search results returned from the Brave Search API. This confirms the MCP server is running, authenticated, and returning data.
Exit the Claude Code session by pressing Ctrl+C or typing /quit.
You have successfully installed a portable Claude Code configuration. Here is what is available in every Claude Code session on this machine:
| Component | Count | What It Does |
|---|---|---|
| Agents | 19 | Specialized subagents for Python, Rust, .NET, SQL, dbt, Kedro, Databricks, MongoDB, documentation, PR management, and more |
| Skills | 21 | Engineering standards, search integrations, PR workflows, and API key management |
| Hooks | 9 | Session names, IDE diagnostics, git rebase enforcement, a database guardrail, search key guards and more (Hooks) |
| MCP Servers | 2 | Brave Search and Tavily for internet search within Claude Code |
Because ~/.claude links into the repository, pulling from Git updates your global configuration:
cd claude-code-config
git pull origin mainRun ./setup.sh --yes again after a pull that adds or removes an agent, skill or hook, so it is linked or pruned; see How to sync across machines.
- How to Add an Agent: create a custom agent for your domain
- How to Add a Skill: create reusable standards for your team
- How to Configure the Statusline: customize billing and usage tracking
- How to Add an MCP Server: integrate new external tools
- How to Run Evals: evaluate skill quality with the skill-creator plugin
- Architecture: understand how the symlink system and agent+skill pattern work
- Design Decisions: why things are designed this way