[opensourcedex]

gentle-shell is a free, open source version control & collaboration project written in TypeScript and released under MIT. It has 1,527 GitHub stars, 248 forks and 369 open issues, and was last pushed 16 hours ago. On this registry it ranks #28 of 50 tracked projects in Version Control & Collaboration, with 5 head-to-head comparisons available. It gained 378 stars over the last 30 tracked days.

What is gentle-shell?

gentle-shell is a senior-architect development harness for the Pi platform that turns a terminal coding agent into a controlled workspace with spec-driven development, focused subagents, strict TDD evidence, review guardrails, and skill discovery.

What it is

gentle-shell is a TypeScript coding agent built for Pi and released under the MIT licence. It is described as a coding-agent workspace that brings changes, tasks, and the engineering workflow into one integrated layout, combining agent orchestration, usage monitoring for supported provider accounts, and built-in diff views. The project is shaped by Gentle-AI and carries the el Gentleman persona layer, which turns stated intent into clear scope, a sensible next step, and evidence that people can review. Around that core sit focused, package-owned Pi agents that can map a codebase, implement a bounded change, or verify it, while a single parent stays accountable for the scope, the decisions, and the final summary.

The problem it addresses is the gap between a terminal that can run an agent and a workspace that helps a developer lead one. A raw coding agent executes, but the tasks, the diffs, the runtime status, and the evidence trail live elsewhere and are hard to inspect. gentle-shell replaces that ad-hoc, single-session terminal use with one inspectable workspace where active tasks, session changes, and runtime status are visible without leaving the work in progress. It also gives the workflow a durable shape through Organic Driven Development (ODD) and optional spec-driven development (SDD) with OpenSpec, so intent, scope, and accepted changes are recorded rather than lost between sessions.

Key capabilities

  • Organic Driven Development (ODD), the recommended everyday path: explore the code, clarify real decisions, implement authorized changes, and run proportionate checks.
  • A single odd/tasks/.md record per task holding objective and problem, scope and constraints, actionable tasks, evidence, progress, next step, and accepted-change rationale.
  • Optional SDD with OpenSpec for substantial work, alongside the lighter ODD path, so teams can escalate formality without making every task feel like a process meeting.
  • Focused package-owned Pi agents for codebase mapping, bounded implementation, and verification, with one parent accountable for scope, decisions, and the final summary.
  • Local-profile session notification through orchestrator_session_id, orchestrator_list, and orchestrator_send_message, advertised as notification-and-ACK transport only.
  • Strict TDD that follows a configured mode, source, and exact runner, forwarded to workers and refreshed on resume, with functional checks still running when TDD is disabled.
  • Engram memory mirroring that reproduces the full task document under project-scoped odd//tasks, plus built-in diff views and usage monitoring in the integrated layout.

Who uses it and how

  • Developers and senior architects who direct a coding agent in the terminal but want the workspace to keep scope, decisions, and evidence in one place.
  • Teams that run ODD for everyday work, using prompts such as "Add CSV export using the existing report filters," and reserve SDD plus OpenSpec for larger, spec-backed changes.
  • Projects where small or read-only tasks need no durable implementation artifacts, and substantial work is delegated to focused workers without entering SDD.
  • Unix users, where presence records sit in the profile's private transport directory and socket endpoints stay below the system temporary directory at no more than 100 encoded bytes.
  • Windows users, where the transport selects a package-local PowerShell helper backed by a Windows named pipe.

Getting started

The README points to a Quickstart and homepage at https://gentle-ai.gentlemanprogramming.com/, alongside documentation and a wiki, for installation and first-run setup. No standalone package name, Docker image, or compose file appears in the supplied facts, so the hosted Quickstart is the entry point to name.

How it compares

No list of paid products this project replaces is provided in the facts, and no competing tools are named either. Within these facts, gentle-shell stands alone in this registry.

When to use it — and when not to

Adopters must accept an operationally involved stack: Engram memory is installed separately, and when it is unavailable local progress survives only with an explicitly pending mirror. The session transport is deliberately small, offering no cross-session queries, offline queue, retries, broadcasts, or read and completion guarantees, so anyone needing reliable delivery or fan-out messaging should look elsewhere. The 369 open issues against 127 forks also suggest an actively churning project, and the last push date in the facts gives no release cadence to judge stability by.

project readme (upstream, from github) — read inline

gentle-shell™

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

npm Pi-native package MIT license GitHub stars Last commit

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

Star History Chart

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 when you choose them

When you explicitly want separate proposal, specification, design, tasks, and verification artifacts, choose SDD/OpenSpec. Configured Strict TDD records RED → GREEN → TRIANGULATE → REFACTOR evidence during apply. TDD is also available in ODD; it does not require SDD.

→ Explore the SDD/OpenSpec flow

Native review — Review the exact change

Review the exact change, not a moving target. Native review keeps one candidate in view, returns risk-scoped evidence, and can surface a bounded correction path. You still decide what happens next in your repository.

→ Read the review integration boundary

What's new in v2.6.0

The v2.6.0 release brings a more persistent, inspectable Pi workspace:

  • Shell: /gentle:changes groups captured write/edit changes from the current agent session and its subagents, without startup repository scans; fullscreen navigation, sidebars, and mouse support stay available. See the capture limits and shell-command coverage.
  • Agents and profiles: the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named /gentle:profiles atomically route the orchestrator independently from packaged and review roles; applying one replaces the routing of every agent, a repository can be pinned to a profile with p so its subagent launches stop following the globally active profile, and the panel shows the routing the runtime actually uses even when models.json is sparse.
  • Control and recovery: native SDD requires parent-confirmed preflight; native review supports intended-untracked selection, consent, and provider continuations. Subsystems install with explicit recovery guidance when npm lifecycle scripts were skipped; Pi Git installs are recognized globally; custom ask responses are opt-in. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.

Also in the box

Capability What it brings to the workspace
Startup and runtime panel A configurable gentle-shell entry point and visible runtime state for Pi.
Skills and delivery guidance Package skills for documentation, issue work, PRs, reviews, and reviewable work units.
Model, effort, persona, and profile controls Explicit knobs for how Pi routes and presents work.
Safety boundaries Guards around destructive operations and sensitive-path handling.
Optional companion packages Extra capabilities you may choose to add; persistent memory is not bundled with gentle-pi.
Optional companions, when they fit your setup
Package Optional role
pi-intercom Cross-session communication where your Pi setup supports it.
gentle-engram Persistent memory, separately installed and configured.
pi-web-access Web access when a task needs it and your policy allows it.
pi-lens Additional inspection surfaces.
@juicesharp/rpiv-ask-user-question Interactive choice support.

These are companions, not hidden prerequisites or a claim that every Pi installation has every capability.

Back to top ↑

Get started

Install the stable release, restart Pi, then synchronize the installed assets.

Naming transition: The product is called gentle-shell; the current npm package and repository remain gentle-pi until migration.

# Published stable release: v2.6.0
pi install npm:gentle-pi@2.6.0

# Restart Pi, then run:
gentle-ai sync

# Start Pi in your project
pi

See the v2.6.0 release notes for version-specific changes.

/gentle:status
/gentle:doctor

RDD is opt-in: enable native receipt-driven development only through an explicit /gentle:review-mode enable decision.

Fullscreen installation note: a recognized global installation persists Pi’s "tuiMode": "fullscreen" setting. Project-local and other install paths do not receive that change.

For prerequisites, source-checkout instructions, full install behavior, and release policy, use the installation reference. For everyday work, describe the outcome and follow ODD. Choose SDD/OpenSpec explicitly only when you want its separate phase artifacts.

Back to top ↑

Documentation

Start with the product-facing destination, then move into the operational reference only when you need the details.

Destination Purpose
gentle-shell reference Workspace layout, changes, usage, agents, and todo interactions.
ODD workflow · Technical reference Everyday work and recovery, optional SDD/OpenSpec, installation, configuration, commands, and contributor detail.
Review integration The provider/consumer boundary for native review.
Native authority architecture Ownership boundaries and review architecture.
Telemetry Approved fields and source limitations.
Delegated verification Practical verification guidance.
Skill style guide The package skill contract.

Back to top ↑

Community

This project is built in public. Bring a real workflow, a sharp question, a bug report, or a small improvement that makes the next person’s work clearer.

GitHub issues Contributors Gentleman Programming Discord

gentle-shell contributors

Back to top ↑

About the author

gentle-shell is built by Alan Buscaglia, the maker behind Gentleman Programming. It grew from a practical belief: capable agents are more useful when the human’s intent, review load, and delivery judgment stay visible all the way through the work.

Startup intro collaboration: thanks to @aporcelli and pi-gentle-startup, which inspired the clean-screen startup animation, compact runtime panel, and pink visual treatment.

Gentleman Programming website Gentleman Programming YouTube Gentleman Programming GitHub

Back to top ↑

Built with the workflow it brings to Pi.

MIT License

Trademark notice: The gentle-shell™ and gentle-pi™ names and associated logos are trademarks of Alan Buscaglia. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.

Frequently asked questions

Is gentle-shell free to use?

gentle-shell is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does gentle-shell do?

Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.

What is gentle-shell written in?

gentle-shell is primarily written in TypeScript. Its source is publicly available at https://github.com/Gentleman-Programming/gentle-shell, and it has 1,527 GitHub stars.