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
- 💻 House Coder - Small code patch execution specialist
- 🏗️ House Planner - Task orchestration and planning specialist
See Future Agents for planned additions (house-vision, house-data).
Main Claude: Uses your selected model (Sonnet 4.5, Opus, etc.) Sub-agents: Mostly use Claude Haiku 4.5 for cost-efficiency and speed Exception: house-planner uses Sonnet 4.5 for complex planning and reasoning
Sub-agents perform specialized, focused tasks (grep, bash parsing, git analysis, code patches) where Haiku 4.5's performance (90% of Sonnet 4.5's agentic coding capability) is more than sufficient. For planning tasks requiring deeper architectural reasoning, house-planner uses Sonnet 4.5. This architecture provides:
- 67% cost savings on most sub-agent operations ($1/$5 vs $3/$15 per million tokens)
- 2x faster response times compared to Sonnet 4 for execution agents
- Appropriate model for each task's complexity level
The main conversation uses your chosen model for complex decision-making, execution agents use the faster, more cost-effective Haiku 4.5, and house-planner uses Sonnet 4.5 for architectural planning.
Note: You can override this by editing agent files and changing model: claude-haiku-4-5-20251001 or model: claude-sonnet-4-5-20250929 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. Test House Coder:
Use house-coder to add a console.log statement at the start of the main function
Expected: Should return a condensed summary with code snippet showing the change
6. Test House Planner:
Use house-planner to create a plan for adding input validation to our forms
Expected: Should return an execution plan with task breakdown and agent assignments
7. Check agents are loaded:
List all available sub-agents
Expected: Should show all six house agents (house-research, house-git, house-bash, house-mcp, house-coder, house-planner)
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.
Use For:
- Implementing small code changes (0-250 lines)
- Fixing import errors and dependencies
- Implementing TODO/FIXME comments
- Applying small bug fixes and patches
- Adding small features (new functions, endpoints)
- Refactoring code sections
Example Invocations:
"Use house-coder to fix the import error in utils.py"
"Implement the TODO in the authentication module with house-coder"
"Add error handling to the login function"
What It Returns:
- Condensed summary with key code snippets
- File:line references for changes
- Test results (if applicable)
- Token savings report (~85-90% savings)
- Recommendations for follow-up actions
Token Savings:
- Full implementation in main: 8,000-15,000 tokens
- House Coder summary: 1,000-1,500 tokens
- Savings: ~85-90% context reduction
Use For:
- Planning complex multi-file changes (3+ files)
- Analyzing ambiguous requirements
- Creating execution plans for new features
- Orchestrating large refactoring efforts
- Breaking down complex tasks into sub-tasks
Example Invocations:
"Use house-planner to plan a JWT authentication system"
"Create an execution plan for refactoring the API layer to async/await"
"Plan the implementation of a new export feature for the dashboard"
What It Returns:
- Detailed execution plan with numbered tasks
- Agent assignments (which house agent for each task)
- Complexity estimates (Low/Medium/High)
- Dependency chains (sequential vs parallel)
- Files to be created/modified
- Clarifying questions (when requirements are ambiguous)
- Risk assessment and recommendations
Note: House Planner uses Sonnet 4.5 (not Haiku) for complex architectural reasoning. It can ask clarifying questions using the AskUserQuestion tool before creating plans.
- 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.