gentle-shell™

Your coding agent for controlled development in the workspace you lead.

Website  ·  Quickstart  ·  Docs  ·  Wiki

Your terminal can run an agent. Your workspace should help you lead it.
gentle-shell is your coding agent, bringing your changes, tasks, and engineering workflow together—built for Pi.

_{One workspace. A coding agent you direct. A workflow you can inspect.}

BUILT FOR PI  ·  Coding-agent workspace  ·  Focused agents  ·  ODD + optional SDD

★ Star gentle-shell on GitHub

_{Built for Pi. Shaped by Gentle-AI.}

Features

gentle-shell — Your coding agent, in the workspace you lead

A complete workspace for the agent you direct. gentle-shell is your coding agent, built for Pi, with native workspace features for agent orchestration, usage monitoring for supported provider accounts, and built-in diff views—all in one integrated layout.

See active tasks, session changes, and runtime status without leaving the work you are leading.

_{gentle-shell in action. Screenshot from Gentle-AI.}

→ Read the gentle-shell reference

el Gentleman — Think before you build

Say what you need once, then keep moving. el Gentleman helps turn intent into clear scope, a sensible next step, and evidence people can review—without making every task feel like a process meeting.

→ Follow the organic workflow and recovery

→ See persona modes and routing

Focused agents — Context with a return path

Bring in help without losing the thread. Focused package-owned Pi agents can map a codebase, implement a bounded change, or verify it, while one parent stays accountable for the scope, the decisions, and the final summary.

→ Learn how work is routed

• orchestrator_session_id, orchestrator_list, and orchestrator_send_message provide local-profile session notifications. List results advertise IDs only and reachability remains unknown. Sending selects the sole advertised peer or asks the user to choose; a successful ACK means the peer accepted the notification for delivery, not that it read or completed work. This is notification-and-ACK transport only: it has no cross-session queries, offline queue, retries, broadcasts, or read/completion guarantees. On Unix, presence records remain in the profile's private transport directory while socket endpoints use a private, profile-hashed directory below the canonical system temporary directory, keeping endpoint length independent of the profile path and at most 100 encoded bytes. The shared system temporary parent is only validated (current-user-owned without group/other write, or root/current-user-owned, world-writable, and sticky); it is never claimed, permissioned, or cleaned up by gentle-pi. On Windows, the transport selects a package-local PowerShell helper for a Windows named pipe; availability and delivery depend on the helper's bounded startup and pipe checks.

ODD — The everyday workflow

Organic Driven Development (ODD) is the recommended path for everyday work: explore the code, clarify real decisions, implement authorized changes, and run proportionate checks. Ask for an outcome, for example: "Add CSV export using the existing report filters." Small/read-only work needs no durable implementation artifacts; substantial work can use focused workers without entering SDD.

One odd/tasks/.md keeps objective/problem/why, scope/constraints, actionable tasks, evidence, progress, next step, and meaningful accepted-change rationale. Engram mirrors the full document under project-scoped odd//tasks; accepted changes update intent and affected tasks while preserving valid completed work. Memory is separately installed; if unavailable, local progress survives with an explicitly pending mirror.

TDD follows configured mode, source, and exact runner, forwarded to workers and refreshed on resume. Tests existing does not enable it; disabled TDD still runs functional checks. Native RDD is separate and user-owned.

Why not SDD every day? Its separate proposal/spec/design/tasks artifacts and phase handoffs add coordination that ordinary work often does not need. Choose SDD explicitly when you want those formal artifacts, never automatically because of size, ambiguity, or risk. SDD remains supported, not deprecated.

→ ODD details and recovery

Optional SDD — Formal phases