House Agents

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

The Problem

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.

The Solution

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

The Four House Agents

1. 🔍 House Research - File and documentation search specialist
2. 🔀 House Git - Git diff and commit analysis specialist
3. ⚡ House Bash - Command execution and output parsing specialist
4. 🔧 House MCP - MCP tool configuration and documentation specialist

See Future Agents for planned additions (house-vision, house-data).

Model Architecture

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.

Quick Start

One-Command Install

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.

Manual Installation

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

How It Works

When you invoke a house agent, Claude Code:

1. Spins up a separate Claude instance with the agent's system prompt
2. Gives it access to specified tools (Read, Grep, Bash, etc)
3. Runs in its own context window (doesn't pollute yours)
4. Returns condensed results to your main conversation

Testing Your Installation

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 /agents command in Claude Code to see all loaded agents
• For house-git: If "no changes" message appears, make some test edits first

Real-World Test Example

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"