{"id":51723145,"url":"https://github.com/josephsenior/Grinta-Coding-Agent","last_synced_at":"2026-08-01T07:00:28.599Z","repository":{"id":338634750,"uuid":"1143615879","full_name":"josephsenior/Grinta-Coding-Agent","owner":"josephsenior","description":"Local-first autonomous coding agent that plans, executes, validates, and finishes software tasks end-to-end.","archived":false,"fork":false,"pushed_at":"2026-07-28T16:22:06.000Z","size":303941,"stargazers_count":27,"open_issues_count":5,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-28T18:07:48.189Z","etag":null,"topics":["ai-coding","autonomous-agent","coding-agent","developer-tools","fastapi","llm","local-first","model-context-protocol","orchestration","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josephsenior.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["josephsenior"]}},"created_at":"2026-01-27T19:53:14.000Z","updated_at":"2026-07-28T16:51:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/josephsenior/Grinta-Coding-Agent","commit_stats":null,"previous_names":["josephsenior/forge-agent","josephsenior/grinta-agent","josephsenior/grinta-coding-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/josephsenior/Grinta-Coding-Agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephsenior%2FGrinta-Coding-Agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephsenior%2FGrinta-Coding-Agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephsenior%2FGrinta-Coding-Agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephsenior%2FGrinta-Coding-Agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josephsenior","download_url":"https://codeload.github.com/josephsenior/Grinta-Coding-Agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josephsenior%2FGrinta-Coding-Agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36148338,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-01T02:00:05.789Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","autonomous-agent","coding-agent","developer-tools","fastapi","llm","local-first","model-context-protocol","orchestration","python"],"created_at":"2026-07-17T15:00:32.874Z","updated_at":"2026-08-01T07:00:28.590Z","avatar_url":"https://github.com/josephsenior.png","language":"Python","funding_links":["https://github.com/sponsors/josephsenior"],"categories":["Applications","Terminal-native coding agents"],"sub_categories":["HTTP","Open Source"],"readme":"# Grinta\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"Grinta logo\" width=\"750\"\u003e\n\u003c/p\u003e\n\n### A local-first autonomous coding agent built to finish long, failure-prone software tasks.\n\n[![Tests](https://github.com/josephsenior/Grinta-Coding-Agent/actions/workflows/py-tests.yml/badge.svg)](https://github.com/josephsenior/Grinta-Coding-Agent/actions/workflows/py-tests.yml)\n[![Lint](https://github.com/josephsenior/Grinta-Coding-Agent/actions/workflows/lint.yml/badge.svg)](https://github.com/josephsenior/Grinta-Coding-Agent/actions/workflows/lint.yml)\n[![Python 3.12–3.13](https://img.shields.io/badge/Python-3.12--3.13-3776AB?logo=python\u0026logoColor=white)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Status: stable](https://img.shields.io/badge/status-stable-2EA44F)](https://github.com/josephsenior/Grinta-Coding-Agent/releases/tag/v1.0.0)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/josephsenior/Grinta-Coding-Agent/releases/download/v1.0.0/grinta_raft.mp4\"\u003e\n    \u003cimg src=\"https://github.com/josephsenior/Grinta-Coding-Agent/releases/download/v1.0.0/grinta-demo-preview.webp\" alt=\"Grinta autonomous coding demo\" width=\"900\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eGrinta in action\u003c/strong\u003e — click the preview to watch the full demo.\u003c/p\u003e\n\nGrinta plans, edits, runs commands, debugs failures, validates the result, and continues until the task is finished. Its control plane and session state stay local; inference can use a major hosted provider or a local model.\n\n[Install](#install) · [Documentation](docs/README.md) · [Architecture](docs/ARCHITECTURE.md) · [Showcase](SHOWCASE.md)\n\n\u003e **4h 33m autonomous run · 16,393 events · 373 tool outcomes · no additional user messages**\n\u003e\n\u003e [Inspect the sanitized execution report](docs/evidence/2026-07-09-autonomous-run-report.md)\n\n## Why Grinta?\n\n- Runs its control plane, execution, session history, and checkpoints locally\n- Works across OpenAI, Anthropic, Google, OpenRouter, Ollama, and LM Studio\n- Uses real Language Server Protocol (LSP) and Debug Adapter Protocol (DAP) integrations\n- Recovers from provider failures, malformed tool calls, timeouts, and context pressure\n- Keeps a durable event ledger, checkpoints, reverts, and inspectable audit trails\n- Exposes Chat, Plan, and Agent workflows in a focused terminal UI\n\n## Install\n\nInstall the stable version from PyPI or source:\n\n```bash\ngit clone https://github.com/josephsenior/Grinta-Coding-Agent.git Grinta\ncd Grinta\npipx install -e .\ngrinta\n```\n\nOr install directly from PyPI:\n\n```bash\npipx install grinta\ngrinta\n```\n\nOptional integrations are available as `grinta[rag]`, `grinta[browser]`, or `grinta[all]`. See the [Quick Start](docs/QUICK_START.md) for Windows, WSL2, Linux, macOS, and provider setup.\n\n## Showcase\n\n| Long-horizon execution | Failure recovery | Raft key-value store |\n| --- | --- | --- |\n| Ran autonomously for **4h 33m**, processed **16,393 events**, and reached `FINISHED` through provider and runtime failures. | Read failing test output, isolated defects, edited the affected code, and reran validation without a follow-up prompt. | Built a Raft-backed key-value store, recovered from a race-condition failure, and finished with **39/39 tests passing**. |\n| [Read the report](docs/showcase/autonomous-4h-session.md) | [Inspect the case study](docs/showcase/compilation-failure-recovery.md) | [Watch and inspect](docs/showcase/raft-kv-store.md) |\n\n[Browse every case study →](SHOWCASE.md)\n\n## How it works\n\n```mermaid\nflowchart TD\n    A[\"Task\"] --\u003e B[\"Plan and act\"]\n    B --\u003e C[\"Local tools\"]\n    C --\u003e D[\"Observe and validate\"]\n    D --\u003e|\"More work or failure\"| B\n    D --\u003e|\"Quality gates pass\"| E[\"Finish\"]\n```\n\nThe `SessionOrchestrator` coordinates model intent, the safety and validation pipeline, local execution, and observations. A durable event stream records the session while completion gates reduce premature “done” states. Read the [architecture guide](docs/ARCHITECTURE.md) for the full component map and [reliability guide](docs/RELIABILITY.md) for recovery behavior.\n\n## Product philosophy\n\nThis table describes Grinta's design commitments—not an unverified performance ranking against other agents.\n\n| Capability | Grinta |\n| --- | :---: |\n| Local control plane | Yes |\n| Provider-agnostic inference | Yes |\n| Local-model support | Yes |\n| LSP integration | Yes |\n| DAP debugging | Yes |\n| Durable session ledger | Yes |\n| Checkpoints and revert | Yes |\n| Terminal UI | Yes |\n| Cloud account required | No |\n\nGrinta is designed for developers who value local execution, provider freedom, inspectable state, and recovery-oriented workflows that can survive long tasks.\n\n## Safety boundary\n\nGrinta runs commands with the privileges of the local user. Policy gates, secret masking, and optional process isolation reduce risk but do not make hostile code safe. Use a VM or container for untrusted repositories and read the [security checklist](docs/SECURITY_CHECKLIST.md) before increasing autonomy.\n\n## Help build Grinta\n\nGrinta is seeking contributors interested in:\n\n- Agent reliability and recovery\n- LSP and debugger integrations\n- Local-model compatibility\n- Terminal user interfaces\n- Autonomous-agent evaluation\n\nStart with a [`good-first-issue`](https://github.com/josephsenior/Grinta-Coding-Agent/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) or read the [Contributor Map](docs/CONTRIBUTOR_MAP.md). The full development workflow is in [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Documentation\n\n- **Use Grinta:** [Quick Start](docs/QUICK_START.md) · [User Guide](docs/USER_GUIDE.md) · [Settings](docs/SETTINGS.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)\n- **Understand it:** [Architecture](docs/ARCHITECTURE.md) · [Reliability](docs/RELIABILITY.md) · [Support Matrix](docs/SUPPORT_MATRIX.md) · [Security](docs/SECURITY_CHECKLIST.md)\n- **Contribute:** [Contributor Map](docs/CONTRIBUTOR_MAP.md) · [Developer Guide](docs/DEVELOPER.md) · [CI](docs/CI.md) · [Roadmap](ROADMAP.md)\n- **Read the engineering story:** [The Book of Grinta](BOOK_OF_GRINTA.md)\n\nCreated and maintained by [Youssef Mejdi](https://github.com/josephsenior). Released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephsenior%2FGrinta-Coding-Agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosephsenior%2FGrinta-Coding-Agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosephsenior%2FGrinta-Coding-Agent/lists"}