# ForgeCode Best Practices - Summary

**Compiled from:** Community feedback, GitHub issues, blog posts, documentation  
**Date Compiled:** April 9, 2026

---

## Quick Start Best Practices

### 1. Disable Telemetry
```bash
export FORGE_TRACKER=false
```
Add to `~/.zshrc` for persistence.

### 2. Configure API Keys Properly
```bash
forge provider login  # Set up providers
```
Consider API key helpers (requested in #2888) for security.

### 3. Verify ZSH Integration
```bash
forge zsh doctor   # Check for issues
forge zsh setup    # Re-run if needed
```

---

## Model Selection Best Practices

### For Speed
- **Opus 4.6** through ForgeCode: Fastest real-world performance
- **Avoid GPT 5.4** through ForgeCode: Unstable tool calling

### For Cost
- **MiniMax M2.1:** Near-SOTA performance at $0.30/$1.20 per million tokens
- **LongCat-Flash-Lite:** Budget option at $0.10/$0.40

### For Reliability
- **Claude Sonnet 4.5:** Best independent benchmark scores
- **Avoid:** Models with known tool calling issues (Qwen 3.5 with current bug)

---

## Agent Usage Best Practices

### Workflow Pattern
1. **Start with `muse`** for planning complex changes
2. **Switch to `forge`** for implementation
3. **Use `sage`** (automatically) for research

### Command Reference
```bash
:muse    # Planning mode
:forge   # Implementation mode
:agent   # View all agents
:new     # Fresh conversation
:compact # Free up token budget
```

---

## Context Management

### Strengths
- **~90% context reduction** vs full-file inclusion
- Function signature indexing
- Selective context pulling

### Limitations
- **No auto-compaction** (unlike Claude Code)
- **No checkpoints/rewind**
- Manual `:compact` required when context full

### Tips
- Use `@filename` for file tagging
- Run `:compact` before long tasks
- Start with `:new` for unrelated tasks

---

## Tool Calling Best Practices

### For Harness Developers
1. Use `old_string`/`new_string` argument names
2. Put `required` before `properties` in JSON schema
3. Flatten nested schemas
4. Add explicit truncation reminders

### For Users
1. **Verify tool calls** - don't blindly accept
2. **Check file paths** - AI can hallucinate paths
3. **Review diffs** - especially for large changes

---

## Pricing Optimization

### Cost Control
1. **Use Sonnet** for routine tasks (cheaper than Opus)
2. **Limit sub-agent spawning** - burns tokens
3. **Use context efficiently** - ForgeCode's indexing helps
4. **Monitor daily limits** - Free tier is 10-50 requests

### Plan Selection
- **Free:** Testing, small projects
- **Pro ($20):** Regular use (<1,000 requests/day)
- **Max ($100):** Power users (1,000-5,000 requests/day)

---

## Project Configuration

### AGENTS.md
Create at project root or `~/forge/AGENTS.md`:
```markdown
# Development Guidelines

## Runtime
- NEVER restart the dev server (runs on port 3000)
- Use npm exclusively (not yarn/pnpm)

## Code Style
- TypeScript strict mode
- Functional programming preferred
```

### Tips
- Be specific and actionable
- Include negative constraints ("NEVER...")
- Reference existing code patterns

---

## Common Pitfalls

### 1. Expecting Claude Code Features
- **Missing:** Checkpoints, auto-memory, IDE extensions
- **Workaround:** Use git commits frequently

### 2. Ignoring Daily Limits
- **Problem:** Task stops mid-execution when limit reached
- **Solution:** Monitor usage, upgrade plan, or switch providers

### 3. Using GPT 5.4 for Research
- **Problem:** Tool calling failures, infinite loops
- **Solution:** Use Opus 4.6 or Sonnet instead

### 4. Privacy Concerns
- **Problem:** Telemetry collects SSH/git data by default
- **Solution:** Set FORGE_TRACKER=false

---

## When to Use ForgeCode vs Alternatives

### Use ForgeCode When:
- Terminal-first workflow
- Speed is priority
- Multi-model flexibility needed
- Open source/auditable code required
- Privacy control essential (with telemetry disabled)

### Use Claude Code When:
- Team collaboration (shared CLAUDE.md)
- Need checkpoints/rewind
- Want auto-memory across sessions
- IDE extensions needed
- Prefer subscription pricing (no separate API costs)

### Use Cursor When:
- IDE-native experience preferred
- GUI features important
- Team using VS Code exclusively

---

## Debugging Tips

### Tool Call Failures
1. Check model compatibility (avoid Qwen 3.5 currently)
2. Verify JSON schema format
3. Try `:retry` to resend

### Performance Issues
1. Use `:compact` to free context
2. Switch to faster model (Sonnet vs Opus)
3. Close unnecessary files with `@[filename]`

### Integration Issues
1. Run `forge zsh doctor`
2. Verify Nerd Font installed
3. Check terminal compatibility (Ghostty has resize bug)

---

## Source References

1. **ForgeCode Docs:** https://forgecode.dev/docs/
2. **ZSH Support:** https://forgecode.dev/docs/zsh-support/
3. **Operating Agents:** https://forgecode.dev/docs/operating-agents/
4. **DEV Community:** https://dev.to/liran_baba/forgecode-vs-claude-code-which-ai-coding-agent-actually-wins-36c
5. **GitHub Issues:** https://github.com/antinomyhq/forgecode/issues