# Show HN: Grinta – a local-first coding agent built for long autonomous runs

> Source: <https://github.com/josephsenior/Grinta-Coding-Agent>
> Published: 2026-07-12 09:39:29+00:00

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](https://github.com/josephsenior).

Direct link if the video does not load: [ docs/assets/grinta-demo.mp4](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/docs/QUICK_START.md).

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

| 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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/docs/evidence/2026-07-09-autonomous-run-report.md)

Full forensic session audits are retained privately.

``` php
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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/docs/CI.md)). Match the tier you are changing before opening a PR ([CONTRIBUTING.md](/josephsenior/Grinta-Coding-Agent/blob/main/CONTRIBUTING.md#testing-before-a-pull-request)).

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](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/preface-why-this-story-matters.md) → [00 · Meaning of Grinta](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/00-the-meaning-of-grinta.md) through the numbered chapters to [45 · The Product Surface Became Real](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/45-the-product-surface-became-real.md) and [46 · The Decomposition Wave](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/46-the-decomposition-wave.md), then the epilogue [07 · The Road Ahead](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/07-the-road-ahead.md). Full index and act structure: [docs/journey/README.md](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/README.md). Stable shortcut from the repo root: [BOOK_OF_GRINTA.md](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/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](/josephsenior/Grinta-Coding-Agent/blob/main/docs/journey/README.md) — engineering memoir; may not reflect the current product surface.

See [CONTRIBUTING.md](/josephsenior/Grinta-Coding-Agent/blob/main/CONTRIBUTING.md).

MIT — see [LICENSE](/josephsenior/Grinta-Coding-Agent/blob/main/LICENSE).

Dependency attribution and notice policy: [THIRD_PARTY_NOTICES.md](/josephsenior/Grinta-Coding-Agent/blob/main/THIRD_PARTY_NOTICES.md).