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.

Grinta in action

Direct link if the video does not load: docs/assets/grinta-demo.mp4.

Release status

• 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.

Why Grinta vs the rest

The pitch in one sentence: a local-first coding agent with deeper built-in tooling than most terminal peers, without locking you to a single model vendor.

Install

Consumer, dev, Windows, WSL2, Linux, macOS: docs/QUICK_START.md

pipx install grinta-ai    # consumer — then cd "<project>" && grinta

Optional extras: pipx install "grinta-ai[rag]" · "grinta-ai[browser]" · "grinta-ai[all]" — details in Quick Start.

What you get

• 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.

Interaction modes

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 use task_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).

Common slash commands

Playbook workflows (/debug, /testing, /feature, …) and the full registry are in /help.

Security boundary

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.

Architecture (high level)

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).

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 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.

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

Run grinta (first interactive launch runs setup) or see docs/SETTINGS.md.

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

Optional completion-quality validation surfaces advisory warnings when tracked work looks incomplete; it does not hard-block the agent from finishing.

Documentation

Start here (end users):

• Quick Start · User Guide · Settings · Troubleshooting

Contributors:

• Contributor Map · Developer Guide · Architecture · CI · Contributing

More reference:

• Documentation hub · Support Matrix · Release checklist · Vocabulary · Security checklist · Roadmap

Optional narrative: The Book of Grinta — engineering memoir; may not reflect the current product surface.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Third-party Notices

Dependency attribution and notice policy: THIRD_PARTY_NOTICES.md.