Local-first. Provider-agnostic. Ships with real LSP + DAP. Optional extras stay opt-in.A terminal coding agent that plans, executes, validates, and finishes — without a cloud control plane, without lock-in to one model vendor, and without the old heavyweight install footprint.
Current status:v1.0.0-rc1
public release candidate. Linux, Windows, and macOS run required unit and extended CI gates; smoke-install and onboarding validation are in place. Remaining GA work is mostly documentation alignment, contributor-doc honesty, and edge-case hardening after the post-rc1 decomposition wave.
Created and maintained by Youssef Mejdi.
Direct link if the video does not load: docs/assets/grinta-demo.mp4.
- Latest public build is
v1.0.0-rc1
(release candidate), not final GA. - Required CI covers sharded Linux unit coverage (75%), cross-platform unit gates, and integration/e2e/stress on Linux, Windows, and macOS; smoke-install and onboarding validation are in place for the current release line.
- We are actively collecting feedback on UX clarity and edge-case reliability before the GA call.
- Linux, Windows, and macOS are supported release targets, but certification depth differs by platform; see
docs/SUPPORT_MATRIX.md. - 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.
Grinta distinguishes itself by focusing on a completely local-first, provider-agnostic, and deeply integrated terminal workflow. Unlike thin wrappers or cloud-dependent control planes, Grinta:
Local-first: Grinta’s control plane, execution, storage, and session history run locally. Model inference may be local or remote depending on the configured provider.Provider-agnostic: Connects seamlessly with OpenAI, Anthropic, Google, OpenRouter, Ollama, or LM Studio using a unified interface.** Deep tooling integration**: Automatically discovers and integrates with local Language Servers (LSP) and Debug Adapters (DAP) on your PATH.** Built-in safety rails**: Classifies actions by risk, implements confirmation gates, and masks secrets in console outputs.** Durable long sessions**: Built with an event-stream ledger supporting automatic compaction, manual checkpoints, and easy reverts.
Consumer, dev, Windows, WSL2, Linux, macOS: docs/QUICK_START.md
pipx install grinta # consumer — then cd "<project>" && grinta
Optional extras: pipx install "grinta[rag]"
· "grinta[browser]"
· "grinta[all]"
— details in Quick Start.
Task completion, not just file edits. Stuck detection, recovery directives, and optional completion-quality validation help reduce 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.Terminal UI. Interactive TTY sessions launch the Textual app with HUD, transcript cards, settings/sessions dialogs, and slash commands; piped input uses a non-interactive fallback.
Grinta exposes three modes in the Textual HUD (Chat, Plan, Agent). They change the conversational contract, not just the prompt tone:
Chat— read-only Q&A and discovery tools; no edits or shell.** Plan**— read-only investigation; may usetask_tracker
for a structured plan when enabled, or prose only. Switch to Agent mode to execute.Agent— full task loop (default for direct work).
Autonomy (/autonomy
: conservative, balanced, full) controls confirmation prompts in Agent mode only. Runtime hardening is configured separately with security.execution_profile
(standard
is the default and supports the interactive terminal and debugger; hardened_local
and sandboxed_local
add stricter policy gates).
| Command | What it does |
|---|---|
/help |
|
| Full slash-command reference | |
/settings |
|
| Model, API key, and MCP configuration | |
/sessions |
|
| List past sessions; `/resume <N | id>` to continue one |
/model |
|
| Show or switch the active provider/model | |
/mode |
|
| View or set interaction mode (chat / plan / agent) | |
/autonomy |
|
| View or set confirmation behavior | |
/cost |
|
| Tokens, calls, USD spent this session | |
/diff |
|
Workspace git changes (--stat , --name-only , --patch ) |
|
/health |
|
| Fast self-check for debug adapters, ripgrep, git, and model setup | |
/checkpoint |
|
| Snapshot the workspace (revertable) | |
/status |
|
HUD snapshot; /status verbose adds diagnostics |
|
/compact |
|
| Force context compaction now |
Playbook workflows (/debug
, /testing
, /feature
, …) and the full registry are in /help
.
Grinta executes actions on the local host. The default standard
profile preserves full interactive terminal and debugger support. hardened_local
adds stricter policy checks but is not sandboxing or process isolation; sandboxed_local
adds process isolation only for non-interactive commands. Read docs/SECURITY_CHECKLIST.md before pointing Grinta at code you do not trust — for hostile codebases, run inside a VM or container.
Grinta is evaluated through recorded long-horizon autonomous sessions and forensic event-stream audits.
A recent full-autonomy run:
- executed for 4h 33m - processed 16,393 events - recorded 373 tool outcomes — 368 successful, 5 failed - produced 123 file events - recovered through inference-provider connection failures
- detected process suspension without misclassifying it as an agent hang
- rejected malformed model tool payloads at the tool boundary
- handled context pressure during execution
- reached the final FINISHED state
The audit recorded one initial user turn and no subsequent user turns during execution.
📊 Read the sanitized autonomous execution report
Full forensic session audits are retained privately.
graph TB
User([User]) --> CLI[CLI: backend.cli.entry]
CLI --> TUI[TTY: Textual TUI]
CLI --> NonInteractive[Piped input: non-interactive runner]
TUI --> Orch[SessionOrchestrator]
NonInteractive --> Orch
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: Linux PR gates shard the unit corpus (backend/tests/unit
) with 75% coverage, then run integration/e2e/stress in extended jobs; Windows and macOS run the same unit corpus plus the extended tier (docs/CI.md). Match the tier you are changing before opening a PR (CONTRIBUTING.md).
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 45 · The Product Surface Became Real and 46 · The Decomposition Wave, 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.
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
Run grinta
(first interactive launch runs setup) or see docs/SETTINGS.md.
Plan -> execute -> observe -> validate -> finish.
Grinta uses compactor strategies to keep long sessions coherent under context limits.
Stuck detection, retry/recovery flows, and circuit breakers are built into orchestration.
Optional completion-quality validation surfaces advisory warnings when tracked work looks incomplete; it does not hard-block the agent from finishing.
Start here (end users):
Contributors:
More reference:
Optional narrative: The Book of Grinta — engineering memoir; may not reflect the current product surface.
See CONTRIBUTING.md.
MIT — see LICENSE.
Dependency attribution and notice policy: THIRD_PARTY_NOTICES.md.