convez.ai
SkillDevOps & InfraestruturaIntermediário
utsavanand

UV Suite

utsavanand/uv-suite

Camada observável com controle para agentes IA de código

Ver no GitHub
BomPluginScore · de 0 a 100

Framework portável para desenvolvimento de software assistido por IA que funciona com Claude Code, Cursor e Codex. Oferece 10 agentes, 9 skills e 5 hooks com observabilidade em tempo real, guardrails anti-slop e memória por sessão através de um dashboard unificado na máquina.

Instalação

$npx convez-ai utsavanand/uv-suite

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
4

Casos de uso

  • Monitorar e controlar múltiplas sessões de desenvolvimento IA concorrentes
  • Aplicar guardrails anti-slop em geração de código automática
  • Manter contexto e checkpoints entre reinicializações de terminal
  • Auditar e aprovar permissões de ferramentas em tempo real

Veredito

Solução robusta e bem-pensada para quem usa agentes de código IA em produção. Destaca-se pela observabilidade real e controle granular, embora exija configuração inicial e familiaridade com CLI.

README

A tradução para o português deste README ainda está na fila.

🛠️ UV Suite

A labeled, observable, anti-slop layer over every AI coding agent you run.

Turn Claude Code, Cursor, or Codex into a named, observable dev environment — with real-time observability and control, anti-slop guardrails, and per-session memory that survives across launches. One dashboard over every session, on your machine.

Install · Quick Start · Start here · Watchtower

Works with Claude Code · Cursor · Codex


Install

npm install -g uv-suite
uvs claude pro                # auto-installs into the current project on first launch

Or with npx:

npx uv-suite install          # explicit install only

Note: The CLI is uvs, not uv. The name uv belongs to Astral's Python package manager and likely already exists on your system.

Quick Start

uvs claude pro                # Claude Code, Professional persona
uvs codex auto                # Codex, Auto persona
uvs pro                       # Shorthand for uvs claude pro
uvs install                   # Explicit install (also runs automatically on launch)
uvs watch                     # Open the Watchtower observability + control dashboard
uvs info                      # Show what's installed

On every uvs launch, you'll be prompted to label the session:

Label this session (Enter to skip — you'll be reminded):
  name:     payments retry refactor
  kind (1=long-running  2=outcome, Enter to skip): 2
  purpose:  ship retry-on-5xx for the Stripe webhook handler
  priority (1=low  2=med  3=high, Enter to skip): 3

Skip any field with Enter. If you skip the name, /uvs-session init will be suggested every few prompts until you label it. Set UVS_NO_PROMPT=1 to suppress prompts entirely.

What it does

🏷️ Named, labeled sessions

Every uvs launch generates a UVS_SESSION_ID and writes metadata to .uv-suite-state/sessions/<id>.json. Two launches in the same repo run as distinct sessions with separate names, checkpoints, and dashboard rows — so concurrent terminals never collide.

🔭 Watchtower — observability and control

uvs watch starts a dashboard at localhost:4200 — Python + embedded SQLite, no Docker and no database to set up. It's a control plane, not just a viewer: stream every session live, then checkpoint, fork, compact, close, or delete any of them from the browser.

🔔 Human in the loop

The Needs human panel surfaces the sessions waiting on you — a tool-permission prompt or an idle wait — with the tool and command as context. Approve / Deny from the browser; for uvs-launched (tmux-owned) sessions the keystroke is sent for you.

🛡️ Anti-slop guardrails

Six guardrails (comment, doc, test, error-handling, over-engineering, and architecture slop) run ambiently on the Pro / Auto personas, catching AI-generated noise as it's written rather than at review time.

📜 Per-session memory

/uvs-session checkpoint writes to uv-out/sessions/<sid>/checkpoints/, and /uvs-session restore auto-picks the current session's latest — so context survives across launches, compaction, and terminal restarts.

Start here

After uvs claude pro, pick the path that matches what you're doing. Each path names the first skill to run and the canonical next steps.

Existing codebase (you didn't write this)

  1. /uvs-understand — builds a knowledge graph + architecture overview in uv-out/map-codebase.md. Other skills (/uvs-architect, /uvs-review, /uvs-review --security) read it automatically.
  2. /uvs-session checkpoint — captures your baseline understanding so /uvs-session restore can bring it back next session.
  3. Then: /uvs-review on the current diff, or /uvs-spec for the next feature.

New project (you're starting from scratch)

  1. /uvs-spec — converts your idea into a structured spec in uv-out/specs/.
  2. /uvs-architect — breaks the spec into Acts with cycle budgets. Reads the spec automatically.
  3. Then: implement Act by Act. Use /uvs-test and /uvs-review per Act.

Reviewing a PR

  1. /uvs-review [branch-name] — reads diff + CLAUDE.md + DANGER-ZONES.md + prior uv-out/ artifacts.
  2. /uvs-review --security if the diff touches auth, payments, data access, or external inputs.

Shipping

  1. /uvs-session checkpoint to capture state.
  2. /uvs-commit — runs review, tests, commits, optionally opens a PR.

Picking a persona (Spike / Sport / Professional / Auto) is a separate axis from picking a first skill — see Personas below for which mode fits which situation.

Sessions and Watchtower

Each uvs launch generates a UVS_SESSION_ID and writes metadata to .uv-suite-state/sessions/<id>.json. This unlocks:

  • Concurrent terminals don't collide. Two uvs launches in the same repo run as distinct sessions with separate names, checkpoints, and dashboard rows.
  • uvs watch shows them all. The Watchtower control plane at localhost:4200 streams every session live and lets you act on them from the browser — see Watchtower at a glance.
  • Per-session checkpoints. /uvs-session checkpoint writes to uv-out/sessions/<sid>/checkpoints/, and /uvs-session restore auto-picks the current session's latest. Pass a session id prefix or name to restore from a different one.
  • Status line shows it all. The Claude Code status bar shows session name, persona, priority, and elapsed time continuously.

Watchtower at a glance

uvs watch starts the dashboard at localhost:4200 — Python + embedded SQLite, no Docker and no database to set up (it provisions its own deps on first run). It's a control plane, not just a viewer, laid out in three panes:

  • Heartbeat (left) — a live, scrolling stream of what every agent is doing, as it happens.
  • Sessions (center) — each session as a flat row (state · tokens · tool calls · last activity). Filter by time / priority / kind and search by name; expand a row to checkpoint, view checkpoint history, compact, fork, close, or delete it.
  • Needs human (right) — sessions waiting on you (a tool-permission prompt or an idle wait), with the tool + command as context. Approve / Deny from the browser; for uvs-launched (tmux-owned) sessions the keystroke is sent for you.

Sessions launched via uvs run inside a transparent tmux so Watchtower can act on them. Hooks forward every Claude Code event (PreToolUse, PostToolUse, UserPromptSubmit, Notification, SessionStart, Stop, ...) with session metadata merged in. A Node-only fallback (no Python) is available via uvs watch --legacy.

Personas

Four modes for different contexts. Pick one when you start a session.

             Spike          Sport        Professional       Auto
             ─────          ─────        ────────────       ────
Purpose      Research       Build new    Ship to prod       Let it run
             & document     things

Model        Opus           Sonnet       Inherit            Inherit
Effort       max            high         high               max

Writes       New files      Anything     Anything           Anything
             only                        (reviewed)         (autonomous)
Edits        Blocked        Allowed      Allowed            Allowed

Guardrails   Doc slop       None         All 6              All 6
Human gates  After each     End only     Every Act          Final output
             map                         boundary           only

When to use what

SituationModeWhy
Joining a new codebaseSpikeUnderstand before changing. Writes docs, not code.
Architecture reviewSpikeMap the system, write ADRs, document findings.
Prototyping a demoSportMove fast, iterate freely, quality comes later.
Hackathon or new projectSportGet the foundation down without review gates.
Fixing a bug in production codeProfessionalEvery change matters. Full review rigor.
Adding a feature to an existing serviceProfessionalTeam depends on this code. Slop-checked.
Well-scoped task with a clear specAutoLet the agent build, test, review end-to-end.
Batch of small tasksAutoAgent handles repetitive work autonomously.

Common progressions:

  • Spike → Sport → Professional (understand, explore, harden)
  • Spike → Auto (research thoroughly, then let the agent execute)
  • Sport → Professional (prototype fast, switch to rigor when it matters)

Skills (slash commands)

12 skills. Each skills/<name>/SKILL.md is a thin orchestrator that dispatches to agents.

CommandWhat it does
/uvs-understand [dir]Map a codebase or whole stack — auto-detects repo vs stack
/uvs-spec [requirements]Write a technical specification
/uvs-architect [spec]Design architecture, decompose into Acts
/uvs-test [file]Write tests or evals: --unit / --integration / --eval (DeepEval compatible)
/uvs-reviewMulti-specialist code review; add --security (OWASP via Semgrep/Gitleaks/Trivy), --slop (anti-slop audit), or --architecture (trace design vs. constraints)
/uvs-prototype [concept]Build a static React prototype
/uvs-qaBrowser QA via Playwright MCP
/uvs-investigateSystematic root-cause debugging
/uvs-commitReview → test → commit (and optionally PR)
/uvs-session init|checkpoint|restore|end|autoSession lifecycle — label, checkpoint, restore, end, or auto-checkpoint
/uvs-lite [on|off]Toggle terse output mode — no preamble, no summaries; persists across turns
/uvs-helpList every skill, agent, hook, guardrail, and persona

Hooks (lifecycle automation)

Fire automatically on Claude Code events. You never invoke these. ~28 scripts live in hooks/.

HookFires onWhat it does
auto-lintFile writeRuns prettier, ruff, or gofmt
slop-grepFile edit/writeAmbient slop detection on sport / professional / auto personas
doc-slop-grepFile edit/writeCatches vague adjectives in markdown on the spike persona
danger-zone-checkFile editWarns if file is in DANGER-ZONES.md
block-destructiveBash commandBlocks rm -rf /, force push to main, DROP TABLE
session-label-nagUserPromptSubmitReminds you to run /uvs-session init every Nth prompt while the session has no name
watchtower-sendAll eventsForwards every event (with session metadata) to the dashboard at localhost:4200
watchtower-notifyNotification / PermissionRequestSurfaces "needs human" approvals to the dashboard
watchtower-tokensStopReports per-session token usage (parsed from the transcript)
watchtower-endSessionEndMarks the session terminated on the dashboard
session-startSessionStartRecords start time, fires bootstrap event with session metadata
session-timerPostToolUseReminders at 45 / 90 / 180 minutes
session-endStopShows duration, today's total, reflection prompt
session-review-reminderStopNudges you to review uncommitted changes
uv-out-*Session eventsManage session-scoped artifacts under uv-out/sessions/<sid>/
status-lineContinuousRenders session label, persona, priority, and timer in the Claude Code status bar

Agents

8 agents. The canonical definitions are agents/claude-code/*.md. The Cursor (.mdc) and Codex (.toml) variants are generated from those by agents/generate.py at install — they're not hand-maintained.

AgentSubsystemModelCycle Budget
CartographerIndexOpus1
Spec WriterActsOpus1
ArchitectActsOpus2
ReviewerGuardOpus1
Test WriterActsSonnet3
Eval WriterActsOpus2
Anti-Slop GuardGuardOpus1
Prototype BuilderActsSonnet3

Artifacts

Agents write persistent output to uv-out/. Each agent reads prior artifacts automatically.

OutputRead by
uv-out/map-codebase.md/uvs-architect, /uvs-review, /uvs-review --security
uv-out/specs/*.md/uvs-architect, /uvs-test, /uvs-test --eval
uv-out/architecture/*.md/uvs-review, /uvs-test, /uvs-review --slop
uv-out/review-*.md/uvs-review --slop, /uvs-review --security
uv-out/sessions/<sid>/checkpoints/*.md/uvs-session restore

Integrations

ToolUsed byPurpose
GraphifyCartographerKnowledge graph from codebase via Tree-sitter
SemgrepSecuritySAST with 4000+ OWASP-mapped rules
GitleaksSecuritySecret detection in git repos
TrivySecurityDependency vulnerability scanning
DeepEvalEval WriterPytest-compatible LLM evaluation
PlaywrightPrototype, Test WriterBrowser automation and e2e testing

Project Structure After Install

.claude/
  settings.json          Permissions and hooks (seeded from your persona on first install)
  agents/                8 agent definitions (canonical .md)
  skills/                12 slash commands
  hooks/                 ~28 hook scripts
  rules/                 6 anti-slop guardrails (Pro / Auto only)
  personas/              4 persona configs
.codex/agents/           8 Codex agent definitions (generated from .claude/agents)
.cursor/rules/           8 Cursor rule definitions (generated from .claude/agents)
AGENTS.md                Codex instruction file
DANGER-ZONES.md          Risky areas (commit this)
.uv-suite-state/         Session metadata + counters (gitignored)
  current-session.txt
  sessions/<sid>.json
uv-out/                  Agent output artifacts (gitignored)
  sessions/<sid>/checkpoints/   Per-session checkpoints

Documentation

DocumentWhat it covers
CONTRIBUTING.mdWorking on UV Suite — adding skills/agents/hooks, running the tests
personas.md4 personas, 7 knobs, when to use each
knowledge/practices.mdWorking principles (honesty, parallelism, scope, completion)
acts-methodology.mdActs delivery framework with worked examples
knowledge/human-in-the-loop.mdCycle budgets, intervention types, learning loops
knowledge/sharing-and-standards.mdDanger zones, team standards, sharing levels
research/landscape.mdOpen source tools and references for each agent
research/comparison.mdUV Suite vs gstack vs Claude Code built-in — feature comparison + prompt-depth deep dive
research/tool-comparison.mdClaude Code vs Cursor vs Codex — how UV Suite works across all three
research/best-practices.mdSubagent patterns, remote sessions, sharing with engineers, cost optimization

Author

Built by Utsav — utsava.xyz.

License

MIT

Ver o original no GitHub

Bom para

Relacionados