Gentleman-Programming/gentle-shell

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

gentle-shell™ – an AI‑powered coding agent for the Pi development environment

What it is – gentle‑shell (distributed as the gentle-pi npm package) is a terminal‑based workspace that lets a large‑language‑model‑backed coding agent run inside your project. The agent can explore the codebase, propose changes, run tests, and present a diff, while you stay in control via a UI that shows active tasks, session changes, and runtime status.

Core ideas

  • Workspace‑centric – the shell presents a single pane (/gentle:… commands) that aggregates the agent’s work, its sub‑agents, and a todo list, so you never leave the terminal.
  • Focused agents – parent sessions can spawn bounded “worker” agents (e.g., map the repo, implement a change, verify it) and receive a concise acknowledgment and evidence back.
  • Organic Driven Development (ODD) – the default workflow encourages lightweight, incremental work: describe the desired outcome, let the agent act, and review the concrete change. A more formal Specification‑Driven Development (SDD) cycle is optional for larger, phase‑gated tasks.
  • Native review – before any change lands, the agent presents a frozen candidate diff for you to approve, reject, or request a correction, keeping the human in the loop.
  • Extensible “companions” – optional packages (gentle-engram, pi-intercom, etc.) add persistent memory, cross‑session messaging, web access, and other capabilities without being required.

Getting started

# Install the latest stable release (v2.6.0 at time of writing)
pi install npm:gentle-pi@2.6.0

# Restart Pi, then sync the assets
gentle-ai sync

# Launch the Pi REPL in your project – the gentle‑shell UI appears
pi

You can then use built‑in commands such as /gentle:status, /gentle:doctor, or /gentle:review-mode enable to inspect the agent, diagnose issues, or turn on the optional review mode.

Key documentation

  • Workspace layout – docs/gentle-shell.md explains the panels, the /gentle:changes view, and how to navigate the UI.
  • ODD workflow – docs/readme-reference.md#organic-driven-development walks through the everyday “intent → outcome” loop.
  • SDD/OpenSpec flow – optional formal phases are described in the same reference under SDD/OpenSpec.
  • Review integration – docs/review-integration.md details the boundary where the agent hands over a concrete diff for human approval.
  • Native authority architecture – docs/native-authority-architecture.md clarifies ownership and safety boundaries for destructive operations.

Community & support

License – MIT (see LICENSE). The project’s trademarks (gentle-shell™, gentle-pi™) are owned by the author, Alan Buscaglia.

gentle-shell is a genuine open‑source tool that brings an LLM‑driven coding assistant directly into the developer’s terminal, offering a structured yet flexible workflow for both quick tweaks and larger, formally‑specified changes.

Related

  • Project
    Deodat-Lawson/LaunchStack

    LaunchStack is a TypeScript‑first, port‑based engine for AI‑native applications, providing ingestion, OCR, RAG, LLM chat, and background‑job infrastructure. A Next.js reference app demonstrates wiring the engine to PostgreSQL + pgvector, S3, Inngest, and Google Gemini (or any OpenAI‑compatible endpoint). Packages are currently unpublished but ready for release; the repo can be run locally or via Docker.

  • Project
    microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator

    A Microsoft Azure‑based reference solution that demonstrates how to build a multi‑agent AI orchestration platform for automating complex business workflows. It combines Azure OpenAI (Foundry), Container Apps, Cosmos DB, and other Azure services, and includes deployment guides, cost guidance, and security recommendations.

  • Project
    lc2panda/alphastream

    Alphastream is an AI‑driven financial analysis web app. It uses DeepSeek/any OpenAI‑compatible LLM with LangGraph to run 14 specialized agents (technical, fundamental, sentiment, risk, etc.) plus four investor‑persona agents. Real‑time market data comes from dual adapters (AKShare & BaoStock) covering Chinese, US, Hong‑Kong, crypto and macro sources. The Next.js + React front‑end shows a dark glass‑morphism UI with chat, dashboards and chart cards, while the Flask backend streams agent progress via SSE. All services can be launched with a single Docker‑Compose command.

  • Project
    Natooz/MidiTok

    MidiTok is a Python package that converts MIDI and abc music files into token sequences for machine‑learning models such as Transformers, enabling music generation, transcription, and other MIR tasks.