agentic-dev-stack
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 6 GitHub stars
Code Fail
- process.env — Environment variable access in bin/cli.mjs
- fs.rmSync — Destructive file system operation in docs/assets/demo/record.mjs
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Smart vibe coding with Claude Code: multi-agent orchestration (Opus plans; Sonnet, Haiku, Gemini, Codex and free models execute), Spec Kit SDD, caveman + RTK + graphify token savings, sandboxed secrets, self-healing free models and a Hermes AI assistant. macOS, Linux, Windows.
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
| Without the stack | With the stack |
|---|---|
| One agent at a time; you are the bottleneck | The lead plans and fans out parallel workers, each in an isolated git worktree |
| Subagents silently inherit Opus | A hook blocks Opus subagents; the default becomes Sonnet; reading goes to Haiku/Gemini |
| Claude quota runs out mid-day | Heavy reading uses Google quota (agy); mechanical edits use free models (NVIDIA via 9Router) |
| "Free models" break every week (410, 404, timeouts) | A curator probes models 3×/day and rewrites the combo on its own |
| Terminal output and context bloat every turn | RTK compresses shell output, caveman trims replies, graphify replaces broad reads |
| Rules live in CLAUDE.md and get ignored | Rules become enforcement: hooks, kernel sandbox, orchestrator policy |
| No spec, giant prompts, blind diffs | Spec Kit SDD: specify → clarify → plan → tasks → analyze → implement → review → verify |
| You only know what happened by opening the laptop | Hermes sends a daily digest + plan of the day to Discord/Telegram |
Measured, not promised
Real numbers from the author's machine, straight from rtk gain --monthly (24,431 shell commands run by agents):
| Month | Commands | Tokens kept out of context | Saved |
|---|---|---|---|
| 2026-09 | 10,215 | 330K | 11.9% |
| 2026-10 | 10,898 | 686K | 14.1% |
| 2026-11 (stack set up early in the month, partial) | 3,318 | 261K | 24.2% |
| Total | 24,431 | 1.3M | 14.6% |
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
| Piece | Role | Why |
|---|---|---|
| Claude Code (Opus) | Lead: plans, decides, integrates, validates | Best reasoning, spent only where it matters |
Sonnet (builder) |
Implements planned units; Opus only for deep/risky ones |
High quality at mid cost |
Haiku (scout) |
Reading and search that needs a shell | Cheap and fast |
| agy · Gemini Flash | Heavy read-only scouting | Uses Google quota, not Claude's |
| agy · Claude Opus / Codex | Independent bug-hunting review | A different provider is a real second opinion |
OpenCode + 9Router free |
Mechanical edits gated by tests | Zero cost; isolated worktree + kernel sandbox |
| alethe | Orchestrator: playbooks, model per task, quota watch, provider switch, cost report | Turns "use more agents" into a reproducible plan |
| GitHub Spec Kit | Spec-driven development | tasks.md becomes the parallel units |
| graphify | Code knowledge graph | Scouts query the graph instead of reading the repo |
| RTK | Compresses shell output | 15–30% fewer input tokens, transparent |
| caveman | Terse replies | Fewer output tokens and less re-read context |
| Hermes Agent | Always-on assistant (no shell) | Digest, alerts and questions from your phone |
| agent-model-guard | Hook that denies Opus subagents | Text rules don't work; enforcement does |
| opencode-safe | Kernel sandbox that denies .env/keys |
Free model + file access = leak risk |
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.
| Other ways | Command |
|---|---|
| Accept the recommended answers | npx agentic-dev-stack setup --yes |
| Answers from a file (CI, dotfiles) | ADS_ANSWERS=answers.json npx agentic-dev-stack setup |
| By phase, no questions | npx agentic-dev-stack install --core --workers --free-models --extras --hermes (or --all, --dry-run) |
| From a clone | ./install.sh --all (macOS/Linux) · .\install.ps1 --all (Windows) |
| One project | npx agentic-dev-stack add-project <dir> (--refresh, --remove, --lang pt-BR) |
| Already set something up by hand | npx agentic-dev-stack adopt (finds jobs, Hermes routines and CLAUDE.md sections that would run twice; replace or keep each) |
| Check / repair / undo | npx agentic-dev-stack doctor [--fix] · npx agentic-dev-stack 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.
| Platform | Support |
|---|---|
| macOS | Full (launchd, sandbox-exec for the free worker) |
| Linux | Full (crontab/systemd, bubblewrap sandbox) |
| Windows | Core, workers, alethe, 9Router, Task Scheduler. The free worker is off by default (no kernel sandbox; use WSL2). Hermes via WSL2 |
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:
- RTK, for shell output;
- caveman, for replies;
- graphify, for reading code;
- 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
- Plan big, execute small: strong model for decisions, cheap model for volume.
- Delegate only when it pays: small or coupled tasks stay with the lead.
- Enforcement over instructions: hooks, sandboxes and policies, not sentences in CLAUDE.md.
- Secrets never leave the machine.
- Deterministic where possible: scripts collect and decide; models summarize and reason.
- 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.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found