I built Claude sub-agents that keep my context clean

⚠️ Beta Software (v0.2.0-beta)

House Agents is in active development. Core features are stable, but agent configurations and APIs may change. Please report issues at GitHub Issues.

Specialized Claude Code sub-agents for context-efficient workflows. Keep your main conversation clean while delegating heavy operations to specialized "house agents."

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)

Total: 133,600 tokens quarantined, ~4,500 added to main context

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

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

Project-Level (this project only):

Copy and paste into Claude Code:

User-Wide (all projects):

Copy and paste into Claude Code:

See INSTALL.md for detailed instructions, troubleshooting, and updating.

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

After installation, test each agent to verify they work:

1. Test House Research:

Expected: Should return a condensed list of TODOs with file:line references

2. Test House Bash:

Expected: Should return a summary of git status (not raw output)

3. Test House Git:

Expected: Should return a condensed summary of changes (not raw diff output)

4. Check agents are loaded:

Expected: Should show house-research, house-git, and house-bash 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

Here's a complete workflow to test all agents:

In Claude Code, try this:

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:

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:

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:

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

• 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)

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):

2. System Prompt (instructions):

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.

1. Not faster - Sub-agents add latency (~2-5s per invocation)
2. No shared memory - Each agent starts fresh (no state between calls)
3. Cost: More API calls, but often fewer total tokens = lower cost
4. Learning curve - Knowing when to use which agent takes practice
5. MCP Tool Access (Known Bug) - Sub-agents currently cannot access MCP tools due to Issue #7296. This affects potential future agents (house-mcp, house-data) that would benefit from MCP integrations. Current production agents (house-research, house-bash, house-git) use built-in tools only.

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: Disabled - waiting for MCP tool access fix
• Purpose: Tool configuration and API documentation specialist
• Blocker: Sub-agents cannot access MCP servers
• ETA: Once Claude Code bug #7296 is resolved

• Status: Planned - researching optimal approach
• Purpose: Screenshot and UI analysis
• Challenge: Image context must be file-based to save tokens
• Use Case: Iterative UI review from screenshot files

• 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:

1. Fork and modify the agent files
2. Share your custom agents
3. 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.