Contributor Map

August 12, 2026 · View on GitHub

Task-oriented entry points for navigating Grinta. Use this before diving into the production tree. For lifecycle and package layout, see DEVELOPER.md and ARCHITECTURE.md.

Bootstrap (first 30 minutes)

bash start_here.sh          # or .\START_HERE.ps1 — installs uv + Python when missing
# Or manually:
uv run python scripts/bootstrap_env.py dev-test
uv run python -m backend.cli.entry          # setup wizard on first launch if unconfigured
PYTHONPATH=. uv run pytest backend/tests/unit -q

End users can install the current GitHub source with pipx; see QUICK_START.md. Contributors should use uv run from a source checkout so dependencies stay isolated.

Where to start by task

If you are changing…	Start here	Tests nearby
CLI commands, startup, slash commands	`launch/entry.py` → `backend/cli/entry.py` → `backend/cli/main.py`; shared slash handlers under `backend/cli/repl/slash_command_*`, TUI in `backend/cli/tui/`, noninteractive runner in `backend/cli/repl/noninteractive.py`, settings under `backend/cli/settings/`	`backend/tests/unit/cli/`
TUI screens and rendering	`backend/cli/tui/app.py`, mixins under `backend/cli/tui/`	`backend/tests/unit/cli/tui/`
Agent step loop (core control plane)	`backend/orchestration/session_orchestrator.py` + mixins in `backend/orchestration/mixins/`	`backend/tests/unit/orchestration/services/`
Middleware (safety, cost, rollback)	`backend/orchestration/mixins/lifecycle.py` (pipeline assembly), files under `backend/orchestration/middleware/`	`backend/tests/unit/orchestration/test_middleware`
Tool execution (bash, edit, grep, browser)	`backend/execution/server/action_execution_server.py`, `backend/engine/tools/`	`backend/tests/unit/execution/`, `backend/tests/unit/engine/`
LLM provider routing and API calls	`backend/inference/llm/`, `backend/inference/provider_resolver.py`	`backend/tests/unit/inference/`
Model catalogs	`backend/inference/catalogs/*.json`	`backend/tests/unit/inference/test_catalog_integrity.py`, `backend/tests/integration/test_inference_model_listing_integration.py`
Context window and compaction	`backend/context/context_pipeline/`, `backend/context/prompt/prompt_window.py`	`backend/tests/unit/context/`
Event stream and durability	`backend/ledger/stream/event_stream.py`, `backend/ledger/stream/durable_writer.py`	`backend/tests/unit/ledger/`
MCP external tools	`backend/integrations/mcp/`, configuration in `backend/execution/mcp/`	`backend/tests/unit/integrations/mcp/`
User settings and config	`backend/core/config/`, `settings.template.json`	`backend/tests/unit/core/`
Safety and command risk	`backend/security/command_analyzer.py`, `backend/orchestration/safety_validator.py`	`backend/tests/unit/security/`

One request, end to end

Typical user message through the stack:

backend/cli/entry.py (startup)
  → backend/cli/main.py
  → backend/cli/tui/main.py or repl/noninteractive.py
  → SessionOrchestrator.step()          backend/orchestration/session_orchestrator.py
    → middleware pipeline               backend/orchestration/middleware/
    → engine plans next Action          backend/engine/
    → ActionExecutionService            backend/orchestration/services/action_execution_service.py
    → RuntimeExecutor                   backend/execution/server/action_execution_server.py
    → Observation                       backend/ledger/observation/
    → EventStream append                backend/ledger/stream/event_stream.py
    → context compaction (if needed)    backend/context/
    → LLM call for next turn            backend/inference/llm/

Large modules (read before you refactor)

Use the generated refactor baseline for current line counts. Prefer extending an existing service or mixin when that is the natural boundary; move public symbols only after checking docs/internals/import-manifest.json.

Orchestration service tests live in backend/tests/unit/orchestration/services/ (mirrors backend/orchestration/services/). The split _app_renderer_event_processor.py monolith now lives under backend/cli/tui/renderer/handlers/.

Inference vs integrations

Layer	Package	Read first
LLM providers	`backend/inference/`	INFERENCE_AND_INTEGRATIONS.md
MCP servers	`backend/integrations/mcp/`	integrations/mcp/README.md
Native agent tools	`backend/engine/tools/` + `backend/execution/`	ARCHITECTURE.md

Do not confuse backend/execution/utils/tool_registry.py (host OS binaries) with backend/engine/tool_registry.py (LLM tool name validation).

Safe change checklist

Find the subsystem row in the table above.
Run the matching unit test directory before and after your edit.
For user-visible behavior, update docs/USER_GUIDE.md or docs/TROUBLESHOOTING.md.
For bugfixes, add a regression test per REGRESSION_TESTS.md.
PR gates: Linux runs the full coverage + extended suite; Windows and macOS run required unit gates — see CI.md.

Platform expectations

Linux, Windows, and macOS are current CI platforms. Linux carries the deepest certification tier; Windows and macOS currently use required unit-test gates — see SUPPORT_MATRIX.md.