Skip to Content
GuidesBest Practices

Best Practices

Guidelines for getting the most out of Agent Harbor based on real-world usage patterns.

Writing Effective Prompts

Be Specific

# Too vague
ah agent start --agent claude --prompt "Fix the bug"
 
# Better - specific location and behavior
ah agent start --agent claude --prompt "Fix the null pointer exception in auth.ts line 42 when user email is empty"

Provide Context

Include relevant context in your prompts:

ah agent start --agent claude --prompt "Add input validation to the UserForm component. The form has email, password, and name fields. Use the existing ValidationUtils from src/utils."

Break Down Large Tasks

Instead of one massive prompt, use follow-up tasks:

# First task: design
ah task create feature/auth --agent claude --prompt "Design the authentication flow for JWT-based auth"
 
# Follow-up: implementation
ah task create --prompt "Implement the login endpoint based on the design"
 
# Follow-up: tests
ah task create --prompt "Add unit tests for the login endpoint"

Project Configuration

Create a Project Config

Add .agents/config.toml to your repository:

# .agents/config.toml
default-agent = "claude"
fs-snapshots = "auto"
 
[sandbox]
type = "local"
allow-network = true

Separate Personal Settings

Keep personal preferences in .agents/config.user.toml (gitignored):

# .agents/config.user.toml
log-level = "debug"
claude-model = "opus"

Document Agent Instructions

Similar to Claude’s CLAUDE.md or Codex’s AGENTS.md, create project-specific guidance:

# .agents/INSTRUCTIONS.md
 
## Project Overview
 
This is a TypeScript React application using Next.js 14.
 
## Coding Standards
 
- Use functional components with hooks
- Prefer named exports
- Use Tailwind CSS for styling
 
## Testing
 
- Run `npm test` before committing
- Minimum 80% code coverage
 
## Common Commands
 
- `npm run dev` - Start development server
- `npm run build` - Production build
- `npm run lint` - Run ESLint

Using Sandboxing Effectively

Always Sandbox Untrusted Tasks

# For tasks that install dependencies or run arbitrary code
ah agent start --agent claude --sandbox local --prompt "Install and configure the new auth library"

Enable Network Only When Needed

# Default: no network (safer)
ah agent start --agent claude --sandbox local --prompt "Refactor the utils module"
 
# With network for package installation
ah agent start --agent claude --sandbox local --allow-network true --prompt "Add axios and configure API client"

Configure Writable Paths for Build Caches

# .agents/config.toml
[sandbox.writable_paths]
paths = [
  "~/.cargo/registry",
  "~/.cache/pip",
  "~/.npm/_cacache",
  "node_modules"
]

Parallel Agent Execution

Compare Multiple Approaches

Launch multiple agents to explore different solutions:

ah task create --agent claude --agent codex --prompt "Implement a caching layer for the API"

Review both results and cherry-pick the best parts.

Scale for Complex Tasks

Use multiple instances for thorough exploration:

ah task create --agent claude --instances 3 --prompt "Find and fix all memory leaks in the application"

Filesystem Snapshots

Choose the Right Provider

ScenarioRecommended Provider
Linux with ZFSzfs
Linux with Btrfsbtrfs
Cross-platform consistencyagentfs
Simple/universal fallbackgit

Use Eager Mode on User Machines

When working on your development machine with background processes:

ah agent start --agent claude --fs-snapshots agentfs --overlay-materialization eager --prompt "Task"

This prevents background file sync or IDE indexing from affecting the agent’s view.

Use Lazy Mode in CI

In controlled environments, lazy mode is faster:

# CI configuration
overlay-materialization = "lazy"

Session Recording

Record Important Sessions

ah agent record -o feature-auth.ahr -- ah agent start --agent claude --prompt "Implement OAuth2"

Use Headless for CI

ah agent record --headless -o ci-run.ahr -- ah agent start --agent claude --non-interactive --prompt "Run full test suite"

Extract Branch Points for Review

ah agent branch-points session.ahr

Time Travel Debugging

Branch When Agent Goes Wrong

When an agent takes a wrong turn, branch from an earlier point:

# Find where it went wrong
ah agent branch-points session.ahr
 
# Start fresh from that point
ah agent start --agent claude --from-snapshot <snapshot-id> --prompt "Instead of that approach, try using the existing AuthService"

Compare Different Approaches

Create branches to explore alternatives:

# Approach 1
ah agent start --from-snapshot <id> --prompt "Use Redis for caching"
 
# Approach 2
ah agent start --from-snapshot <id> --prompt "Use in-memory LRU cache"

MCP Integration

Configure Useful Tools

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "/path/to/docs"]
    }
  }
}

Use Project-Specific MCP Config

# Create per-project MCP configuration
ah agent start --agent claude --mcp-config .agents/mcp.json --prompt "Create GitHub issue for the bug"

Terminal Multiplexer Integration

Match Your Existing Setup

Configure Agent Harbor to use your preferred multiplexer:

# ~/.config/agent-harbor/config.toml
multiplexer = "tmux"

Use Named Sessions

ah tui --multiplexer tmux

Agent Harbor creates and manages sessions automatically.

ConfigurationOverview