2026-07-06 18:32 UTCIn-site rewrite5 min readUpdated: 2026-07-06 18:48 UTC

Show HN: Grinta – local-first AI coding agent that passed 106-minute stress test

Grinta is a local-first, provider-agnostic AI coding agent that passed a 106-minute stress test. It offers deep built-in tooling including LSP and DAP integration, safety rails, session checkpointing, and works with multiple model providers. Current release is v1.0.0-rc1.

SourceHacker News AIAuthor: JosephSenior

Notifications You must be signed in to change notification settings

Fork 2

Star 18

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1,610 Commits

.cursor

.devcontainer

.github

.trunk

.vscode

backend

docs

examples

launch

logs

packaging

scripts

traces/ouroboros

.dockerignore

.env.template

.gitattributes

.gitignore

.hintrc

.nvmrc

.pre-commit-config.yaml

.prettierignore

.prettierrc.json

.pylintrc

BOOK_OF_GRINTA.md

CHANGELOG.md

CITATION.cff

CODE_OF_CONDUCT.md

COMMUNITY.md

CONTRIBUTING.md

DOCKER_START.ps1

GOVERNANCE.md

LICENSE

MAINTAINERS.md

MANIFEST.in

Makefile

README.md

ROADMAP.md

SECURITY.md

START_HERE.ps1

SUPPORT.md

THIRD_PARTY_NOTICES.md

build.sh

docker_start.sh

grinta_raft.mp4

mypy.ini

pydoc-markdown.yml

pyproject.toml

pytest.ini

settings.bench.json

settings.template.json

start_here.sh

uv.lock

Repository files navigation

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

Grinta Aider Claude Code Codex CLI

Provider-agnostic (OpenAI / Anthropic / Google / Ollama / LM Studio / OpenRouter) ✅ ✅ ❌ Anthropic only ❌ OpenAI only

Local-first (works fully offline w/ Ollama) ✅ auto-detected partial ❌ ❌

LSP integration (auto-discovers 40+ language servers on PATH) ✅ ❌ partial ❌

DAP debugger integration ✅ auto-discovered ❌ ❌ ❌

Cost / token / latency HUD ✅ live partial ❌ partial

Stuck-loop + cost-acceleration detection ✅ ❌ partial ❌

Risk-classified actions + audit log ✅ ❌ partial partial

Session checkpoint / resume / revert ✅ event-stream ✅ git partial ❌

Windows-supported workflow (PowerShell) ✅ partial partial partial

MCP support ✅ ❌ ✅ strong partial

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 "" && 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//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

Command What it does

/help Full slash-command reference

/settings Model, API key, and MCP configuration

/sessions List past sessions; /resume 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.

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.

About

Local-first autonomous coding agent that plans, executes, validates, and finishes software tasks end-to-end.

Topics

python

orchestration

developer-tools

fastapi

local-first

autonomous-agent

llm

ai-coding

model-context-protocol

coding-agent

Resources

Readme

License

MIT license

Code of conduct

Contributing

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

18 stars

Watchers

0 watching

Forks

2 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 99.5%

Other 0.5%