agentic-dev-stack: smart vibe coding with Claude Code

Stop running one AI agent at a time. This is a production-ready setup for Claude Code:

• the expensive model (Opus) plans;
• cheap and free models execute;
• a reviewer from another provider checks the diff;
• every turn spends the minimum number of tokens.

It includes spec-driven development with GitHub Spec Kit, token savings with caveman + RTK + graphify, multi-agent orchestration with alethe, kernel-sandboxed secrets, self-healing free models through 9Router, and an always-on Hermes assistant on Discord or Telegram. One command on macOS, Linux and Windows.

🇧🇷 Leia em português · 📘 The smart vibe coding guide · 🧩 CLAUDE.md / AGENTS.md templates

npx agentic-dev-stack

_{A short setup wizard (like create-next-app) asks what you want, then installs and configures everything, including the free models and the Discord/Telegram bot. Re-run it any time to update or change settings.}

Why

Measured, not promised

Real numbers from the author's machine, straight from rtk gain --monthly (24,431 shell commands run by agents):

That is one developer and one workload, and November is a partial month, so read it as a trend, not a benchmark. Savings from delegation (subagents, alethe) and caveman are not measured here yet. Measure your own after a week or two:

rtk gain --monthly                                                  # shell output savings
python3 -I ~/.agents/skills/alethe/scripts/orchestrate.py report    # per-run cost, models and providers

Share your numbers in an issue: a table of real results from different setups is worth more than any claim.

Architecture

_{Editable source: docs/assets/architecture.excalidraw (open at excalidraw.com).}

The workflow

The full guide, Smart vibe coding: the complete guide, covers:

• how caveman, RTK, graphify and Spec Kit SDD fit together;
• a day in the life;
• prompting patterns and anti-patterns;
• checklists.

Who does what

Details: docs/01-architecture.md.

Install

npx agentic-dev-stack            # interactive setup: pick components, it does the rest
npx agentic-dev-stack new my-app # new project (optional Next.js/Vite/Astro/Python + Spec Kit), already wired

The wizard asks only what it cannot detect, verifies what you type (NVIDIA key, bot tokens), and automates what used to be manual: 9Router provider, free combo, API key and OpenCode wiring; caveman, Spec Kit and graphify installs; Discord invite link; Telegram ID detection; Hermes routines; wiring the repos you pick. Nothing is written until you confirm, and running it again opens pre-filled with Update / repair · Change settings · Wire more projects · New project · doctor · Uninstall.

Everything is re-runnable, backs up what it edits and never deletes your content. Third-party tools are installed at pinned versions (config/versions.json), and the CLI tells you when a new release of the stack is out. Prerequisites: Node ≥ 18, git and Claude Code; Python ≥ 3.9 for alethe, the curator and the digest. Per-OS details: docs/02-installation.md.

CI runs the test suite (including the wizard) and a real --core install on Ubuntu, macOS and Windows (PowerShell), on Node 22 and 24.

Templates for your projects

• templates/project/CLAUDE.md: a starter CLAUDE.md covering SDD, token economy, delegation and definition of done.
• templates/project/AGENTS.md: the cross-agent version (Codex, OpenCode, Antigravity, Cursor), with the worker contract.
• Portuguese versions are in templates/pt-BR/.

Hermes: your always-on dev assistant

Scripts collect the data; Hermes summarizes it. Every morning you get a digest with:

• free-model status, token usage and available updates;
• Spec Kit progress and an AI radar;
• yesterday's work and hours per project;
• 3 priorities for today.

The docs also include 10 productive recipes: CI triage, uptime/SSL checks, weekly CVEs, a phone inbox that becomes tasks, billable hours, client-friendly release notes and more. Works on Discord or Telegram. → docs/06-hermes.md

Documentation

FAQ

What is "smart vibe coding"?
You steer intent and decisions; agents do the typing. "Smart" means spec first, cheap models for volume, independent review, verification before "done", and minimal tokens. See the guide.

How do I save tokens in Claude Code?
Stack four things:

1. RTK, for shell output;
2. caveman, for replies;
3. graphify, for reading code;
4. a lean CLAUDE.md, with one topic per chat.

Then stop paying Opus prices for reading and boilerplate: delegate those to Haiku, Gemini, Sonnet and free models.

Can I use free models with Claude Code?
Yes, as workers: OpenCode + 9Router with free NVIDIA NIM models. The curator keeps them healthy, and the sandbox makes sure they never see your secrets.

How do I run multiple Claude Code agents in parallel?
Two ways: native subagents (scout/builder/reviewer) with worktree isolation, or alethe playbooks such as parallel-worktrees for Spec Kit [P] tasks.

Does it work with Codex, Gemini, Kiro or Copilot CLI?
Codex is a native alethe provider (WITH_CODEX=1); the others plug in as custom workers. See docs/04.

Does it work on Windows?
Yes for the core, workers, orchestration and schedules (PowerShell, Task Scheduler). The free-model worker needs a kernel sandbox, so on Windows run it under WSL2.

Will it delete or overwrite my files?
No. It only appends blocks between BEGIN/END markers, merges JSON settings, and backs up every file it edits to ~/.local/share/agentic-dev-stack/backups/. uninstall and add-project --remove take out only those blocks and entries.

Is it safe?

• Third-party pieces were audited and pinned to a reviewed version.
• The free worker is blocked from reading secrets at the kernel level.
• Hermes runs without a shell.

See docs/07-security.md.

Principles

1. Plan big, execute small: strong model for decisions, cheap model for volume.
2. Delegate only when it pays: small or coupled tasks stay with the lead.
3. Enforcement over instructions: hooks, sandboxes and policies, not sentences in CLAUDE.md.
4. Secrets never leave the machine.
5. Deterministic where possible: scripts collect and decide; models summarize and reason.
6. Audit before installing: third-party code is read and pinned.

Contributing

Issues and PRs are welcome: new worker adapters, Linux/Windows sandboxes, Hermes recipes, translations. Start with CONTRIBUTING.md; security reports go through SECURITY.md (privately). Release notes: CHANGELOG.md.

License

MIT. Third-party tools keep their own licenses.