5.8 KiB

Raw Blame History

Claudish for AI Agents

How Claude Code sub-agents should use Claudish. Technical reference.

This guide is for AI developers building agents that integrate with Claudish, or for understanding how Claude Code's sub-agent system works with external models.

The Problem

When you run Claude Code, it sometimes spawns sub-agents via the Task tool. These sub-agents are isolated processes that handle specific tasks.

If you're using Claudish, those sub-agents need to know how to use external models correctly.

Common issues:

Sub-agent runs Claudish in the main context (pollutes token budget)
Agent streams verbose output (wastes context)
Instructions passed as CLI args (limited, hard to edit)

The Solution: File-Based Instructions

Never run Claudish directly in the main context.

Instead:

Write instructions to a file
Spawn a sub-agent that reads the file
Sub-agent runs Claudish with file-based prompt
Results written to output file
Main agent reads results

The Pattern

Step 1: Write Instructions

# Main agent writes task to file
cat > /tmp/claudish-task-abc123.md << 'EOF'
## Task
Review the authentication module in src/auth/

## Focus Areas
- Security vulnerabilities
- Error handling
- Performance issues

## Output Format
Return a markdown report with findings.
EOF

Step 2: Spawn Sub-Agent

// Use the Task tool
Task({
  subagent_type: "codex-code-reviewer",  // Or your custom agent
  description: "External AI code review",
  prompt: `
    Read instructions from /tmp/claudish-task-abc123.md
    Run Claudish with those instructions
    Write results to /tmp/claudish-result-abc123.md
    Return a brief summary (not full results)
  `
})

Step 3: Sub-Agent Executes

# Sub-agent runs this
claudish --model openai/gpt-5.1-codex --stdin < /tmp/claudish-task-abc123.md > /tmp/claudish-result-abc123.md

Step 4: Read Results

# Main agent reads the result file
cat /tmp/claudish-result-abc123.md

Why This Pattern?

Context protection. Claudish output can be verbose. If streamed to main context, it eats your token budget. File-based keeps it isolated.

Editable instructions. Complex prompts are easier to write/edit in files than CLI args.

Debugging. Files persist. You can inspect what was sent and received.

Parallelism. Multiple sub-agents can run simultaneously with separate files.

Recommended Models by Task

Task	Model	Why
Code review	`openai/gpt-5.1-codex`	Trained for code analysis
Architecture	`google/gemini-3-pro-preview`	Long context, good reasoning
Quick tasks	`x-ai/grok-code-fast-1`	Fast, cheap
Parallel workers	`minimax/minimax-m2`	Cheapest, good enough

Sub-Agent Configuration

Set environment variables for consistent behavior:

# In sub-agent environment
export CLAUDISH_MODEL_SUBAGENT='minimax/minimax-m2'
export OPENROUTER_API_KEY='...'

Or pass via CLI:

claudish --model minimax/minimax-m2 --stdin < task.md

Error Handling

Sub-agents should handle Claudish failures gracefully:

#!/bin/bash
if ! claudish --model x-ai/grok-code-fast-1 --stdin < task.md > result.md 2>&1; then
  echo "ERROR: Claudish execution failed" > result.md
  echo "See stderr for details" >> result.md
  exit 1
fi

File Naming Convention

Use unique identifiers to avoid collisions:

/tmp/claudish-{purpose}-{uuid}.md
/tmp/claudish-{purpose}-{uuid}-result.md

Examples:

/tmp/claudish-review-abc123.md
/tmp/claudish-review-abc123-result.md
/tmp/claudish-refactor-def456.md
/tmp/claudish-refactor-def456-result.md

Cleanup

Don't leave temp files around:

# After reading results
rm /tmp/claudish-review-abc123.md
rm /tmp/claudish-review-abc123-result.md

Or use a cleanup script:

# Remove files older than 1 hour
find /tmp -name "claudish-*" -mmin +60 -delete

Parallel Execution

For multi-model validation, run sub-agents in parallel:

// Launch 3 reviewers simultaneously
const tasks = [
  Task({ subagent_type: "codex-reviewer", model: "openai/gpt-5.1-codex", ... }),
  Task({ subagent_type: "codex-reviewer", model: "x-ai/grok-code-fast-1", ... }),
  Task({ subagent_type: "codex-reviewer", model: "google/gemini-3-pro-preview", ... }),
];

// All execute in parallel
const results = await Promise.allSettled(tasks);

Each sub-agent writes to its own result file. Main agent consolidates.

The Claudish Skill

Install the Claudish skill to auto-configure Claude Code:

claudish --init

This adds .claude/skills/claudish-usage/SKILL.md which teaches Claude:

When to use sub-agents
File-based instruction patterns
Model selection guidelines

Debugging

Check if Claudish is available:

which claudish || npx claudish@latest --version

Verbose mode for debugging:

claudish --verbose --debug --model x-ai/grok "test prompt"

Check logs:

ls -la logs/claudish_*.log

Common Mistakes

Running in main context:

// WRONG - pollutes main context
Bash({ command: "claudish --model grok 'do task'" })

Passing long prompts as args:

# WRONG - shell escaping issues, hard to edit
claudish --model grok "very long prompt with special chars..."

Not handling errors:

# WRONG - ignores failures
claudish --model grok < task.md > result.md

Summary

Write instructions to file
Spawn sub-agent
Sub-agent runs Claudish with --stdin
Results written to file
Main agent reads results
Clean up temp files

This keeps your main context clean and your workflows debuggable.

Automation - Scripting patterns
Model Mapping - Configure sub-agent models

5.8 KiB Raw Blame History