codehydra
ativin4/codehydra
BYOS terminal coding agent: CLI/model/effort routing across Claude, Gemini, Codex CLIs
Instalação
npx convez-ai ativin4/codehydra1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
🐍 CodeHydra: The BYOS Terminal Coding Agent
Bring Your Own Subscription (BYOS). CodeHydra is a zero-GUI, autonomous coding agent that bypasses pay-per-token API gates by scavenging local OAuth session tokens from your official developer tools.
⚡ Core Superpowers
- Subscription Scavenging: Automatically finds and uses tokens from
Claude Code,Gemini CLI,GitHub Copilot/Codex, andGoogle Cloud ADC. - OSS Model Fallback: Falls back to Ollama (local or cloud) during rate-limits or refresh windows — set
OLLAMA_HOSTfor a remote instance; no subscription gap means no conversation interruption. - Multi-CLI Gateway: Routes each turn to
claude,gemini,codex, orollamabased on effort tier and which subscriptions/daemons are active, with automatic fallback if one fails. - Agentic Passthrough: The chosen CLI edits files directly (auto-approve/yolo mode) — no fragile diff-parsing required.
- Live Streaming: Responses render incrementally, token-by-token, as
claude/geminiproduce them (viastream-json). - Persistent Claude Session:
clauderuns as a long-livedstream-jsonprocess, reused across turns - only the first turn pays CLI startup cost, and/mode//modelchanges or a new conversation transparently restart it. - Claude Code-style TUI: A scrollable history pane with a pinned input box at the bottom, built with
textual. - Self-Healing Loop: If the agent makes a change that breaks your build, it reads the
stderrand fixes it automatically. - Workspace-Aware: Injects a compact AST-tree map of your entire project into the LLM context.
- Sessions: Conversation history, routing state, and usage are persisted to
.codehydra/sessions/and resumable across runs. - Usage Tracking:
/costsummarizes which CLI/model/tier handled each turn and token counts where reported. - MCP Native: Declare MCP servers in
.agentrc.tomland they're wired into whichever backend CLI is active. - Autonomous Subagents: Every backend CLI is given a built-in
dispatch_agentstool (mirroring Claude Code's Task tool) so it can fan independent sub-tasks out to parallel CodeHydra-routed agents on its own, mid-turn. - Background Tasks: The same built-in toolset gives the CLI
run_in_background/get_background_output/stop_background_task(mirroring Claude Code's background Bash + Monitor) for long-lived processes like dev servers, surviving past the current turn. - Configurable Routing: Override CLI priority and model choices per tier in
.agentrc.tomlwithout touching code.
🚀 Quick Start
1. Prerequisites
Ensure you have uv installed:
curl -LsSf https://astral.sh/uv/install.sh | sh
2. Installation
git clone https://github.com/ativin4/codehydra.git
cd codehydra
uv sync
3. Usage
# Start the interactive TUI
uv run python3 main.py
4. Configure Self-Healing
Add a .agentrc.toml to your project root to enable build verification:
[build]
command = "pytest" # or "npm run build", "go build", etc.
🛠️ Commands
| Command | Action |
|---|---|
/effort <low|medium|high> | Set the effort tier (affects model choice) |
/cli <auto|claude|gemini|codex|ollama> | Pin the backend CLI for the session |
/model <name|auto> | Pin an exact model, bypassing the routing table |
/mode <plan|yolo> | plan = read-only (no edits/commands); yolo = auto-approve everything (default) |
/login <claude|gemini|codex|ollama> | Launch auth flow (or show setup/model info for Ollama) |
/parallel "task 1" "task 2" ... | Run multiple prompts concurrently (each in its own CLI process), results shown as they complete |
/sessions | List saved sessions |
/resume [id] | Resume a session (defaults to the most recent other than current) |
/cost | Show per-turn CLI/model/tier and token usage for this session |
/clear | Reset conversation history |
/exit | Terminate session |
🤖 OSS Model Fallback (Ollama)
Use Ollama as a fallback when your paid subscriptions hit rate limits:
Local
# Install: https://ollama.com/download
ollama pull llama3.2 # or mistral, qwen2.5-coder, deepseek-r1, etc.
# Then in CodeHydra:
/cli ollama # pin to ollama for the session
/model llama3.2 # pick any pulled model
/login ollama # shows available models + usage hint
Cloud / remote Ollama instance
export OLLAMA_HOST=https://your-ollama-host
# CodeHydra detects it automatically on next start (or /login ollama to refresh)
Ollama is detected on startup and added as the last-tier fallback, activating automatically when claude/gemini/codex all fail.
⚙️ Configuration (.agentrc.toml)
Beyond the [build] command, .agentrc.toml supports:
- MCP servers (
[mcp.servers.<name>]): declared servers are passed to whichever CLI is active via its native MCP config (claude--mcp-config, gemini.gemini/settings.json, codex-c mcp_servers.*). - Routing overrides (
[routing]): set a custom CLI try-order (priority), override the default model per CLI/tier ([routing.models.<cli>]), or override the auto-mode model try-order ([routing.model_map]).
See the commented examples in .agentrc.toml.
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for details.
📄 License
Distributed under the MIT License. See LICENSE for more information.