josephsenior/Grinta-Coding-Agent

A local-first coding agent built to finish long, failure-prone software tasks.
Grinta can inspect a repository, plan a change, edit files, run commands, debug
failures, validate the result, and keep going until the task is complete. The
control plane, command execution, session history, and checkpoints stay on your
machine; inference can use a hosted provider or a local model.
Grinta in action — click the preview to watch the full run.
Quick start ·
How it works ·
User guide ·
Architecture ·
Showcase ·
Contributing
At a glance
| | |
| --- | --- |
| **Interface** | Terminal UI plus a non-interactive, pipe-friendly runner |
| **Workflows** | Chat, Plan, and Agent modes |
| **Execution** | Local file operations, shell commands, git, LSP, DAP, and MCP tools |
| **Inference** | Hosted providers, OpenAI-compatible endpoints, Ollama, LM Studio, and vLLM |
| **Durability** | Persisted sessions, event history, checkpoints, restore, and trajectory export |
| **Safety** | Confirmation levels, command risk analysis, workspace boundaries, and optional hardened execution profiles |
| **Platforms** | Linux, Windows, macOS, and WSL2 |
| **Runtime** | Python 3.12 or 3.13 |
Why Grinta?
Many coding agents work well when the first plan succeeds. Long tasks are
different: providers time out, tools return malformed output, tests expose new
failures, context windows fill up, and processes get interrupted. Grinta is
designed around that reality.
- **Local-first control:** your repository, execution, session state, and
checkpoints remain local.
- **Recovery-oriented execution:** retries, circuit breakers, stuck detection,
and explicit lifecycle states help the agent recover instead of silently
stopping.
- **Validation before completion:** task tracking and completion gates reduce
false “done” results.
- **Inspectable history:** a durable event ledger records actions and outcomes
for recovery, debugging, and audit.
- **Provider freedom:** choose a hosted model, an OpenAI-compatible gateway, or
a local inference server.
- **Developer tooling:** Grinta can use language servers and debug adapters in
addition to ordinary file and shell tools.
> **4h 33m autonomous run · 16,393 events · 373 tool outcomes · no additional user messages**
>
> Inspect the sanitized execution report.
Quick start
1. Install
The recommended installation uses pipx so Grinta is
isolated from your project dependencies:
If grinta is not found after installation, run pipx ensurepath, restart the
terminal, and try again.
To install the current repository version instead:
2. Configure
Run the setup wizard and choose a provider and model:
API keys are stored in Grinta's local configuration area. You can also provide
them through environment variables such as OPENAI_API_KEY,
ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY. See the
settings reference for configuration precedence and secret
handling.
3. Open a project
Start Grinta from the repository you want it to work on:
Or specify the project explicitly:
Then describe a concrete outcome, for example:
The first interactive launch can also guide you through setup. For platform-
specific instructions, including WSL2, see the Quick Start guide.
Choose the right workflow
Switch modes at any time with /mode.
| Mode | Best for | Tool access |
| --- | --- | --- |
| **Chat** | Understanding code, asking questions, exploring an unfamiliar repository | Read-only discovery |
| **Plan** | Investigating a change and producing an implementation plan before editing | Read-only investigation and task planning |
| **Agent** | Implementing, testing, debugging, and validating a complete change | Full configured execution surface |
Agent mode also has three autonomy levels, selected with /autonomy:
| Level | Confirmation behavior |
| --- | --- |
| conservative | Confirms shell commands, edits, MCP calls, and delegation |