Specialized Claude Code sub-agents for context-efficient workflows. Keep your main conversation clean while delegating heavy operations to specialized "house agents."
Featured in: 800+ hours of Learning Claude Code in 8 minutes by Edmond Yong
When working on complex tasks in Claude Code, your context window fills up with:
- Verbose search results from 100+ files
- Long API documentation pages
- npm install logs and build output
- Accumulated conversation history
This "context pollution" reduces Claude's effectiveness and wastes tokens.
House Agents are specialized Claude Code sub-agents that run in their own context windows. Each agent handles specific heavy operations and returns condensed results to your main conversation.
Measured in Production
Recent validation from actual usage:
- house-research: 70,100 tokens processed → 3,246 returned (95.4% savings)
- house-git: 42,900 tokens processed → ~500 returned (98.8% savings)
- house-bash: 20,600 tokens processed → ~700 returned (96.6% savings)
- house-mcp: 53,300 tokens processed → ~540 returned (99.0% savings)
Total: 187,000 tokens quarantined, ~5,000 added to main context
- 🔍 House Research - File and documentation search specialist
- 🔀 House Git - Git diff and commit analysis specialist
- ⚡ House Bash - Command execution and output parsing specialist
- 🔧 House MCP - MCP tool configuration and documentation specialist
See Future Agents for planned additions (house-vision, house-data).
Main Claude: Uses your selected model (Sonnet 4.5, Opus, etc.) Sub-agents: Use Claude Haiku 4.5 for cost-efficiency and speed
Sub-agents perform specialized, focused tasks (grep, bash parsing, git analysis) where Haiku 4.5's performance (90% of Sonnet 4.5's agentic coding capability) is more than sufficient. This architecture provides:
- 67% cost savings on sub-agent operations ($1/$5 vs $3/$15 per million tokens)
- 2x faster response times compared to Sonnet 4
- Appropriate model for each task's complexity level
The main conversation uses your chosen model for complex decision-making, while sub-agents use the faster, more cost-effective Haiku 4.5 for heavy-lifting operations.
Note: You can override this by editing agent files and changing model: claude-haiku-4-5-20251001 to model: inherit to use the main conversation's model.
Project-Level (this project only):
Copy and paste into Claude Code:
Clone https://github.com/houseworthe/house-agents. Detect my OS and use appropriate commands to copy the .claude directory to my current project (use Git Bash commands on Windows if available, otherwise try PowerShell). After copying, verify all three agent files exist in .claude/agents/ directory. Then list all available sub-agents to confirm they're loaded. Finally, test house-research by asking it to find all TODO comments in the codebase - make sure to invoke it correctly as a sub-agent.
User-Wide (all projects):
Copy and paste into Claude Code:
Clone https://github.com/houseworthe/house-agents. Detect my OS and create ~/.claude/agents/ directory (or Windows equivalent %USERPROFILE%\.claude\agents\). Copy all .md files from the cloned repo's .claude/agents/ to that directory using OS-appropriate commands. List the installed files, then list all available sub-agents to confirm they loaded. Test house-research by finding README files in the current directory - invoke it as a sub-agent.
# 1. Clone the repository
git clone https://github.com/houseworthe/house-agents.git /tmp/house-agents
# 2. Install project-level (current project only)
cp -r /tmp/house-agents/.claude .
# OR install user-wide (all projects)
mkdir -p ~/.claude/agents
cp /tmp/house-agents/.claude/agents/*.md ~/.claude/agents/
# 3. Verify installation
ls .claude/agents/ # or: ls ~/.claude/agents/See INSTALL.md for detailed instructions, troubleshooting, and updating.
When you invoke a house agent, Claude Code:
- Spins up a separate Claude instance with the agent's system prompt
- Gives it access to specified tools (Read, Grep, Bash, etc)
- Runs in its own context window (doesn't pollute yours)
- Returns condensed results to your main conversation
After installation, test each agent to verify they work:
1. Test House Research:
Use house-research to find all TODO comments in the codebase
Expected: Should return a condensed list of TODOs with file:line references
2. Test House Bash:
Use house-bash to check the current git status
Expected: Should return a summary of git status (not raw output)
3. Test House Git:
Use house-git to review my current git diff
Expected: Should return a condensed summary of changes (not raw diff output)
4. Test House MCP:
Use house-mcp to help me understand how to configure an MCP server
Expected: Should return a minimal example config with usage instructions
5. Check agents are loaded:
List all available sub-agents
Expected: Should show house-research, house-git, house-bash, and house-mcp in the list
Troubleshooting:
- If agents don't show up, run
ls .claude/agents/to verify files exist - If agents error, check the agent files for syntax errors
- User-level agents:
ls ~/.claude/agents/to verify installation - Try
/agentscommand in Claude Code to see all loaded agents - For house-git: If "no changes" message appears, make some test edits first
Here's a complete workflow to test all agents:
In Claude Code, try this:
1. Use house-research to find all console.log statements in my codebase
2. Use house-bash to run "npm test" and analyze any failures
3. Use house-git to review my recent git changes
What you should see:
- House Research returns: List of files with console.log + line numbers (not full file contents)
- House Bash returns: Test summary with pass/fail counts (not full npm output)
- House Git returns: Change summary by impact (Critical/Medium/Minor) (not raw diff output)
All in condensed format (3k-8k tokens total instead of 50k+).
Use For:
- Searching large codebases (20+ files)
- Finding patterns across multiple files
- Extracting info from documentation
- Locating TODO comments, deprecated APIs, security issues
Example Invocations:
"Use house-research to find all React components using useEffect"
"Search for all API endpoints with house-research"
"Find all TODO comments in the backend"
What It Returns:
- Condensed findings with source references (
file:line) - Pattern summaries across files
- Actionable next steps
- Real example: Codebase search across 10+ files processed 70k tokens, returned 3.2k (95.4% savings)
Use For:
- Running build commands
- Executing test suites
- Running deployment scripts
- Multi-step command sequences
Example Invocations:
"Use house-bash to run npm test and analyze failures"
"Run the build with house-bash and check for warnings"
"Execute the deployment script"
What It Returns:
- Clear success/failure status
- Error analysis with suggested fixes
- Key metrics (test counts, build time)
- Relevant output snippets (not full logs)
- Parsed summaries instead of raw command output
Use For:
- Reviewing large diffs (100+ line changes)
- Branch comparison before merging
- Commit history analysis
- Merge conflict identification
- Change impact assessment
Example Invocations:
"Use house-git to review my staged changes"
"Compare feature-branch with main using house-git"
"Analyze the last 10 commits with house-git"
What It Returns:
- Summary: X files changed, Y insertions, Z deletions
- Key changes by impact (Critical/Medium/Minor)
- Changes grouped by file type (source/tests/config/docs)
- Merge conflict locations (if applicable)
- Recommendations for review focus
Use For:
- Configuring MCP servers (Context7, Notion, Puppeteer, etc.)
- Reading verbose API documentation
- Generating minimal working configs
- Understanding tool integration requirements
- Progressive disclosure of complex documentation
Example Invocations:
"Use house-mcp to help configure the Context7 MCP server"
"How do I set up [any MCP server]?"
"Generate a minimal config for [any API/tool]"
What It Returns:
- Minimal working configuration (20-30 lines max)
- One clear usage example
- Critical gotchas only (deal-breakers, not nice-to-haves)
- Progressive disclosure (summary first, details on request)
- Condensed documentation summaries
Note: House MCP automatically inherits all MCP tools configured in your environment. No setup needed - it works with whatever servers you have.
- Large codebases (100+ files)
- Verbose documentation (10+ pages)
- Long command output (npm install, test runs)
- Multi-step workflows (search → configure → execute)
- When hitting context limits (conversation getting sluggish)
- Simple tasks (single file edits)
- Small codebases (<20 files)
- Interactive debugging (tight feedback loops)
- Quick commands (ls, git status)
- Learning/exploration (when you want full context)
Main Claude Code Session
├── Clean context
├── Focus on implementation
└── Receives condensed results from:
│
├─→ House Research (separate context)
│ ├── Searches 70k+ tokens across 10+ files
│ └── Returns 3k token summary (95% savings)
│
├─→ House Git (separate context)
│ ├── Analyzes 43k token diff
│ └── Returns 500 token summary (98% savings)
│
└─→ House Bash (separate context)
├── Processes 21k+ tokens of command output
└── Returns 700 token summary (97% savings)
Heavy operations happen in agent contexts, not yours.
✅ "Use house-research to find all components"
❌ "Find all components" (main Claude might search inefficiently)
"Use house-research to find all API endpoints, then use house-bash to run the integration tests"
✅ "Use house-research to analyze the auth system"
❌ "Use house-research to read auth.js" (too specific, just use Read)
Agents are focused on their specialty - review their findings before implementing changes.
Each agent file (.md format with YAML frontmatter) has two parts:
1. Frontmatter (metadata):
name: house-research
description: "When to use this agent"
tools: Read, Grep, Glob
model: inherit2. System Prompt (instructions):
You are the House Research Agent...
[detailed instructions for the agent]
Edit the agent files to customize:
- Which tools each agent can access
- The agent's behavior and output format
- Token budgets and priorities
- When the agent should be invoked proactively
Project-level (.claude/agents/ in project):
- Available only in this project
- Project-specific customizations
- Committed to git (if you want)
User-level (~/.claude/agents/):
- Available in ALL your projects
- Personal preferences and defaults
- Not in version control
Claude Code loads both, with project-level taking precedence.
- Not faster - Sub-agents add latency (~2-5s per invocation)
- No shared memory - Each agent starts fresh (no state between calls)
- Cost: More API calls, but often fewer total tokens = lower cost
- Learning curve - Knowing when to use which agent takes practice
- MCP Tool Access (Partial Workaround) - Sub-agents had limited MCP tool access due to Issue #7296. A workaround was discovered: omitting the
tools:field allows sub-agents to inherit all MCP tools from the main session. This enabled house-mcp (now in production). The limitation still affects house-data which requires specific database MCP servers not yet widely available.
See USAGE.md for detailed examples:
- Refactoring a large codebase
- Configuring complex integrations
- Running CI/CD pipelines
- Multi-agent workflows
The following agents are planned but not yet implemented due to technical limitations:
- Status: Research completed - not proceeding with implementation
- Purpose: Screenshot and UI analysis with token savings
- Finding: Fresh screenshots pasted into Claude Code are embedded as image data in master context, consuming tokens immediately before delegation is possible
- Technical limitation: Sub-agents can only receive text prompts via the Task tool. Master instance must consume image tokens before it can describe the image to a sub-agent
- Possible but not useful: Could work with pre-saved image files (master receives path, sub-agent reads), but this doesn't match typical screenshot workflow
- Conclusion: No significant token savings achievable for primary use case
- Status: Planned - requires CLI tool prerequisites
- Purpose: Database query and CSV analysis
- Challenge: Needs database CLI tools (sqlite3, psql, mysql)
- Blocker: MCP database servers also affected by bug #7296
Want to contribute? See CONTRIBUTING.md for agent development guidelines.
These agents are templates - customize them for your workflow:
- Fork and modify the agent files
- Share your custom agents
- Report issues or suggest improvements
MIT - Use however you want
Built for Claude Code users who work on complex projects and want to keep their context clean and focused.