From 0ec02b0fa597d76c7c33076590d88560f5ca3c96 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Fri, 23 Jan 2026 08:58:21 +0100 Subject: [PATCH] docs: add subscription token limits & Goose comparison MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enrichir la section subscription limits (ultimate-guide.md): - Tableau des budgets tokens par plan (Pro 44K, Max 88-220K) - Ratio Opus/Sonnet 8-10× documenté explicitement - Clarification "heures" = temps de traitement, pas tokens - Lien vers ccusage (outil communautaire de monitoring) - Note historique sur réductions non annoncées (Oct 2025) Nouvelle section Goose dans ai-ecosystem.md: - Comparaison technique Claude Code vs Goose (7 critères) - Stats GitHub (15K+ stars, 350+ contributors) - Use cases et trade-offs honnêtes - Hardware requirements selon LLM - Quick start avec commandes d'installation Sources: Perplexity research (Jan 2026), official Anthropic docs, community reports (Reddit, GitHub issues, HN). Co-Authored-By: Claude --- guide/ai-ecosystem.md | 93 +++++++++++++++++++++++++++++++++ guide/ultimate-guide.md | 38 +++++++++++--- machine-readable/reference.yaml | 9 +++- 3 files changed, 130 insertions(+), 10 deletions(-) diff --git a/guide/ai-ecosystem.md b/guide/ai-ecosystem.md index 23ce622..68216d3 100644 --- a/guide/ai-ecosystem.md +++ b/guide/ai-ecosystem.md @@ -20,6 +20,7 @@ - [9. Cost & Subscription Strategy](#9-cost--subscription-strategy) - [10. Claude Cowork (Research Preview)](#10-claude-cowork-research-preview) - [11. AI Coding Agents Matrix](#11-ai-coding-agents-matrix) +- [11.1 Goose: Open-Source Alternative (Block)](#111-goose-open-source-alternative-block) - [12. Context Packing Tools](#12-context-packing-tools) - [Appendix: Ready-to-Use Prompts](#appendix-ready-to-use-prompts) - [Alternative Providers (Community Workarounds)](#alternative-providers-community-workarounds) @@ -1113,6 +1114,98 @@ An **interactive comparison matrix** of 23 AI coding agents across 11 technical --- +## 11.1 Goose: Open-Source Alternative (Block) + +For developers hitting Claude Code's subscription limits or needing model flexibility, [Goose](https://github.com/block/goose) is a notable open-source alternative worth understanding. + +### What Is Goose? + +An **on-machine AI coding agent** developed by Block (formerly Square), released under Apache 2.0 license. Unlike Claude Code, Goose runs entirely locally and is **model-agnostic**—it can use Claude, GPT, Gemini, Groq, or any LLM provider. + +| Metric | Value (Jan 2026) | +|--------|------------------| +| **GitHub Stars** | 15,400+ | +| **Contributors** | 350+ | +| **Releases** | 100+ since Jan 2025 | +| **License** | Apache 2.0 (permissive) | +| **Primary Language** | Rust (64%) + TypeScript (26%) | + +### Claude Code vs Goose: Key Differences + +| Aspect | Claude Code | Goose | +|--------|-------------|-------| +| **LLM Flexibility** | Claude only | Any LLM (GPT, Gemini, Claude, Groq, local models) | +| **Deployment** | Cloud (Anthropic servers) | Local only (on your machine) | +| **Cost Model** | Subscription ($20-$200/mo) | Free + your LLM API costs | +| **Rate Limits** | Anthropic's weekly/5-hour caps | Your LLM provider's limits | +| **Token Visibility** | Opaque (no per-prompt tracking) | Full transparency | +| **MCP Support** | Native (growing ecosystem) | 3,000+ MCP servers available | +| **Setup Complexity** | Simple (npm install) | Moderate (Rust toolchain, API keys) | + +### When to Consider Goose + +**Good fit**: +- You're hitting Claude Code's weekly limits frequently +- You need model flexibility (e.g., GPT for some tasks, Claude for others) +- You require full cost visibility and control +- You work with large, multi-language codebases requiring aggressive refactoring +- You want offline capability (with local models like Ollama) + +**Poor fit**: +- You want simplicity over flexibility +- You prefer fixed monthly cost vs. variable API billing +- You value Claude's specific reasoning capabilities and can't substitute +- You don't want to manage LLM API credentials + +### Trade-offs + +| Goose Advantage | Goose Limitation | +|-----------------|------------------| +| No subscription limits | LLM API costs can escalate unpredictably | +| Model choice | Requires self-managed API keys | +| Full token transparency | No built-in cross-session memory | +| Open source (contribute back) | Smaller user base, fewer tutorials | +| Offline with local models | Local models inferior for complex tasks | + +### Hardware Requirements + +Goose itself is lightweight (Rust binary). The requirements depend on your LLM choice: + +| LLM Type | Requirements | +|----------|-------------| +| **Cloud APIs** (Claude, GPT, Gemini) | Minimal (just network access) | +| **Local models** (Ollama, etc.) | 16-32GB RAM, GPU recommended for larger models | + +### Quick Start + +```bash +# macOS +brew install goose + +# Or via cargo +cargo install goose-cli + +# Configure LLM provider +goose configure +``` + +See [Goose Quickstart](https://block.github.io/goose/docs/quickstart/) for detailed setup. + +### Positioning + +Goose is **not a replacement** for Claude Code—it's an alternative with different trade-offs. The right choice depends on your priorities: + +| Priority | Choose | +|----------|--------| +| Simplicity, Claude's reasoning | Claude Code | +| Cost control, model flexibility | Goose | +| Fixed monthly budget | Claude Code subscription | +| Pay-per-use, no limits | Goose + API | + +For most developers already invested in Claude Code workflows, the switching cost is significant. Goose is most valuable for teams needing model diversity or developers frequently hitting Claude Code's limits. + +--- + ## 12. Context Packing Tools When working with LLMs on large codebases, **context packing** refers to techniques for extracting and feeding relevant code context to the model efficiently. diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 2a1553d..e96e0ab 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -1936,23 +1936,41 @@ Monthly cost estimate: $50-$200 for 5-10 developers **How Subscription Limits Work** -Unlike API usage (pay-per-token), subscriptions use a different model: +Unlike API usage (pay-per-token), subscriptions use a hybrid model that's deliberately opaque: | Concept | Description | |---------|-------------| -| **Message windows** | Limits reset periodically (e.g., every few hours), not daily | -| **Hybrid counting** | Advertised as "messages" but actual capacity varies by message length, attachments, and context size | -| **Weekly caps** | Higher tiers may have weekly limits to prevent continuous 24/7 usage | -| **Model weighting** | Opus consumes quota faster than Sonnet; Haiku is lightest | +| **5-hour rolling window** | Primary limit; resets when you send next message after 5 hours lapse | +| **Weekly aggregate cap** | Secondary limit; resets every 7 days. Both apply simultaneously | +| **Hybrid counting** | Advertised as "messages" but actual capacity is token-based, varying by code complexity, file size, and context | +| **Model weighting** | **Opus consumes 8-10× more quota than Sonnet** for equivalent work | + +**Approximate Token Budgets by Plan** (Jan 2026, community-verified) + +| Plan | 5-Hour Token Budget | Weekly Sonnet Hours | Weekly Opus Hours | Claude Code Access | +|------|---------------------|---------------------|-------------------|-------------------| +| **Free** | 0 | 0 | 0 | ❌ None | +| **Pro** ($20/mo) | ~44,000 tokens | 40-80 hours | N/A (Sonnet only) | ✅ Limited | +| **Max 5x** ($100/mo) | ~88,000-220,000 tokens | 140-280 hours | 15-35 hours | ✅ Full | +| **Max 20x** ($200/mo) | ~220,000+ tokens | 240-480 hours | 24-40 hours | ✅ Full | + +> **Warning**: These are community-measured estimates. Anthropic does not publish exact token limits, and limits have been reduced without announcement (notably Oct 2025). The 8-10× Opus/Sonnet ratio means Max 20x users get only ~24-40 Opus hours weekly despite paying $200/month. + +**Why "Hours" Are Misleading** + +The term "hours of Sonnet 4" refers to **elapsed wall-clock time** during active processing, not calendar hours. This is not directly convertible to tokens without knowing: +- Code complexity (larger files = higher per-token overhead) +- Tool usage (Bash execution adds ~245 input tokens per call; text editor adds ~700) +- Context re-reads and caching misses **Tier-Specific Strategies** | If you have... | Recommended approach | |----------------|---------------------| +| **Pro plan** | Sonnet only; batch sessions, avoid context bloat | | **Limited Opus quota** | OpusPlan essential: Opus for planning, Sonnet for execution | -| **Moderate quota** | Sonnet default, Opus only for architecture/complex debugging | -| **Generous quota** | More Opus freedom, but still monitor weekly usage | -| **Unlimited/high tier** | Use Opus freely, focus on productivity over optimization | +| **Max 5x** | Sonnet default, Opus only for architecture/complex debugging | +| **Max 20x** | More Opus freedom, but still monitor weekly usage (24-40h goes fast) | **The Pro User Pattern** (validated by community): @@ -1970,8 +1988,12 @@ This is exactly what OpusPlan mode does automatically (see Section 2.3). /status # Shows current session: cost, context %, model ``` +Anthropic provides no in-app real-time usage metrics. Community tools like [`ccusage`](https://github.com/ryoppippi/ccusage) help track token consumption across sessions. + For subscription usage history: Check your [Anthropic Console](https://console.anthropic.com/settings/usage) or Claude.ai settings. +**Historical Note**: In October 2025, users reported significant undocumented limit reductions coinciding with Sonnet 4.5's release. Pro users who previously sustained 40-80 Sonnet hours weekly reported hitting limits after only 6-8 hours. Anthropic acknowledged the limits but did not explain the discrepancy. + ### Context Poisoning (Bleeding) **Definition**: When information from one task contaminates another. diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index e27c447..53fad50 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -78,7 +78,10 @@ deep_dive: context_triage: 1448 session_vs_memory: 1481 fresh_context_pattern: 1525 - subscription_limits: 1914 + subscription_limits: 1933 + subscription_token_budgets: 1948 + subscription_opus_ratio: 1946 + subscription_monitoring: 1985 plan_mode: 2100 rewind: 2278 mental_model: 2360 @@ -174,7 +177,9 @@ deep_dive: ai_ecosystem_workflows: 10590 ai_ecosystem_integration: 10716 ai_ecosystem_detailed: "guide/ai-ecosystem.md" - ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1114" + ai_ecosystem_goose: "guide/ai-ecosystem.md:1116" + ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132" + ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208" ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449" ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959" voice_refine_skill: "examples/skills/voice-refine/SKILL.md"