convez.ai
AgenteAutomaçãoAvançado
josephsenior

Grinta – Agent Autônomo de Codificação

josephsenior/Grinta-Coding-Agent

Agent de código autônomo, agnóstico a provedor, local-first com LSP/DAP

Ver no GitHub
BomPluginScore · de 0 a 100

Agent CLI local-first que planeja, executa, valida e finaliza tarefas de software end-to-end sem dependência de cloud ou lock-in de provedor. Suporta múltiplos modelos (OpenAI, Anthropic, Google, Ollama) com integração nativa de LSP e DAP, instalação mínima (~1.4 MB) e rodagem offline completa.

Instalação

$npx convez-ai josephsenior/Grinta-Coding-Agent

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
33
Forks
6
Acompanhando
0
Saúde
100%
Último commit
há 1 dia
Versão
v1.0.0
Issues abertas
6
Contribuidores
1

Casos de uso

  • Automação de tarefas de desenvolvimento de software completas
  • Implementação de features sem intervenção manual constante
  • Debug e validação automática de código com integração de debugger
  • Desenvolvimento local offline com modelos locais (Ollama)

Veredito

Grinta é uma solução madura (RC v1.0.0) para automatização de codificação que diferencia-se pela filosofia local-first, baixo overhead (1.4 MB) e agnositicismo de provedor. Recomendado para desenvolvedores que buscam agent de código robusto sem lock-in ou dependência de cloud.

README

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

Grinta

Grinta logo

License: MIT Python 3.12+ Install: pipx mypy: checked code style: Ruff Tests Lint CLI Regression Release Stage: RC

Local-first. Provider-agnostic. Ships with real LSP + DAP. ~1.4 MB wheel.

A CLI coding agent that plans, executes, validates, and finishes — without a cloud control plane, without lock-in to one model vendor, and without a 1.6 GB install.

Current status: v1.0.0-rc1 public release candidate. Intended for real-world use, with focused community feedback requested before GA.

Grinta in action

Full session recording (~2.5 min, with audio):

Direct link if the player does not load: grinta-demo.mp4.

Release status

  • Latest public build is v1.0.0-rc1 (release candidate), not final GA.
  • We are actively collecting feedback on first-run setup, UX clarity, and edge-case reliability.
  • If you hit friction, please open an issue with the RC Feedback template from the issue chooser.
  • GA criteria and release gate details live in docs/RELEASE_CHECKLIST.md.

Why Grinta vs the rest

GrintaAiderClaude CodeCodex CLI
Install size (base wheel)1.4 MB~80 MB~15 MB~12 MB
Provider-agnostic (OpenAI / Anthropic / Google / Ollama / LM Studio / OpenRouter)✅✅❌ Anthropic only❌ OpenAI only
Local-first (works fully offline w/ Ollama)✅ auto-detectedpartial❌❌
LSP integration (auto-discovers 17 servers)✅❌partial❌
DAP debugger integration✅ auto-discovered❌❌❌
Cost / token / latency HUD✅ livepartial❌partial
Stuck-loop + cost-acceleration detection✅❌partial❌
Risk-classified actions + audit log✅ hardened_local❌partialpartial
Session checkpoint / resume / revert✅ event-stream✅ gitpartial❌
Windows-first parity (PowerShell)✅partialpartialpartial
MCP support✅❌✅ best in classpartial

The pitch in one sentence: everything Aider's local-first ethos gives you, plus the depth of tooling Claude Code has, without locking you to a single model vendor.

Install in 30 seconds

pipx install grinta-ai          # lean install (~few MB) — all you need for coding
grinta init                     # one-time wizard: pick provider + paste key
grinta                          # launch the REPL in the current directory

Optional extras (install only what you need):

pipx install "grinta-ai[rag]"        # adds chromadb (~80MB ONNX model) for vector memory
pipx install "grinta-ai[documents]"  # adds PDF / DOCX / PPTX / LaTeX parsing
pipx install "grinta-ai[browser]"    # adds browser-use for web automation
pipx install "grinta-ai[all]"        # everything

That is the whole setup. The grinta init wizard auto-detects local Ollama and LM Studio servers and writes a working settings file for you. Installed runs use ~/.grinta/settings.json; source checkouts use the repository settings.json; APP_ROOT can intentionally override that root. Other install paths (uv, Homebrew, Scoop, and experimental Docker image usage) are in docs/INSTALL.md.

What you get

  • Task completion, not just file edits. Validation gates and stuck detection block premature "done".
  • Model-agnostic. OpenAI, Anthropic, Google, OpenRouter, Ollama, LM Studio — same prompt surface, same tools.
  • Local-first. Code stays in your workspace; sessions, checkpoints, and audit logs live under ~/.grinta/workspaces/<id>/storage.
  • Strong safety rails. Risk-classified actions, CRITICAL refusal gate, secret masking, and a session-wide audit trail.
  • Durable long sessions. Event-stream ledger, automatic compaction, manual /checkpoint, and revert.
  • Lean TUI. Cost / tokens / latency / breaker state visible in the HUD; rich slash commands (/help).

Common slash commands

CommandWhat it does
/helpFull slash-command reference
/costTokens, calls, USD spent this session
/diffWorkspace git changes (--stat, --name-only, --patch)
/sessionsRecent sessions, with optional limit (/sessions list 10)
/thinkToggle the optional reasoning scratchpad
/checkpointSnapshot the workspace (revertable)
/statusFull HUD snapshot
/compactForce context compaction now

Security boundary

Grinta executes actions on the local host. hardened_local adds stricter policy checks but is not sandboxing or process isolation. Read docs/SECURITY_CHECKLIST.md before pointing Grinta at code you do not trust — for hostile codebases, run inside a VM or container.

Architecture (high level)

graph TB
    User([User]) --> CLI[CLI: backend.cli.entry]
    CLI --> Orch[SessionOrchestrator]
    Orch --> Engine[Engine\nplanning + tool intent]
    Orch --> Pipe[Operation pipeline\nsafety + validation]
    Pipe --> Runtime[RuntimeExecutor\nlocal execution]
    Runtime --> Obs[Observations]
    Obs --> Orch
    Orch --> Ledger[EventStream / durability]
    Orch --> FinishGate[Task validation\nbefore finish]

See docs/ARCHITECTURE.md for the deep dive.

Contributors: CI runs the full unit corpus on Linux and Windows (docs/CI.md); match that locally before opening a PR (CONTRIBUTING.md).

The story behind Grinta

Grinta is a single-author project, written and rewritten in public. The journey — what was killed, what was wrong, what got rebuilt — is The Book of Grinta: start at Preface → 00 · Meaning of Grinta through the numbered chapters to 44 · The Empty Folder Trials, then the epilogue 07 · The Road Ahead. Full index and act structure: docs/journey/README.md. Stable shortcut from the repo root: BOOK_OF_GRINTA.md.

Quick start (from source)

Windows (recommended)

.\START_HERE.ps1

Linux / macOS / manual

  1. Install dependencies in this repo’s environment only (creates/updates .venv/; do not rely on a global pip install mixed with unrelated tools):
uv sync --group browser

Optional dev/test tools: uv sync --group dev --group test --group browser.

  1. Create local settings:
uv run python -m backend.cli.entry init
  1. Start the CLI:
uv run python -m backend.cli.entry

If you previously installed grinta-ai with pip into a global interpreter, remove it (pip uninstall grinta-ai) and use uv run from this repository so dependencies stay isolated.

Docker (community / experimental)

Use the container image directly (no official compose stack in this repo):

docker run -it --rm -v "$PWD:/work" -w /work \
  -e LLM_API_KEY=${LLM_API_KEY} \
  ghcr.io/josephsenior/grinta:latest

LLM Setup (settings.json)

When installed through pipx, Homebrew, or Scoop, settings are resolved from ~/.grinta/settings.json. When running from a source checkout, settings resolve from the repository root unless APP_ROOT is set.

Minimal config:

{
  "llm_provider": "openai",
  "llm_model": "openai/gpt-4o-mini",
  "llm_api_key": "${LLM_API_KEY}",
  "llm_base_url": ""
}

For manual setup, put the real value in a sibling .env file or your shell environment as LLM_API_KEY; avoid keeping the only copy of a secret directly in settings.json.

Common model ids:

  • openai/gpt-4o-mini
  • anthropic/claude-sonnet-4-20250514
  • google/gemini-2.5-pro
  • ollama/llama3.2

Core Concepts

Full task loop

Plan -> execute -> observe -> validate -> finish.

Context compaction

Grinta uses compactor strategies to keep long sessions coherent under context limits.

Reliability controls

Stuck detection, retry/recovery flows, and circuit breakers are built into orchestration.

Completion integrity

Task validation can block finish calls when tracked work is incomplete.

Documentation

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Third-party Notices

Dependency attribution and notice policy: THIRD_PARTY_NOTICES.md.

Ver o original no GitHub

Bom para

Relacionados