SHUMORA / GETTING STARTED

Start with Shumora.

Shumora is an open-source desktop workspace for developers running multiple Pi Coding Agent sessions. It keeps independent terminals, Council discussions, and Git review in one app—not a replacement chat interface or a bundled AI model.

Install and connect Pi

Download Shumora. Get the installer from Shumora Releases. Available artifact formats include Linux AppImage, Windows installer, and macOS DMG/ZIP. Choose the correct OS and architecture.
Prepare Pi separately. Install Pi and configure access to a model provider. Shumora uses an external Pi installation; downloading Shumora does not bundle Pi or model access. The app’s Library also exposes setup controls for supported npm installations.
Check executable discovery. Pi should be available as pi on the app’s PATH. Desktop launches can inherit a different PATH from your shell. If discovery fails, set PI_EXECUTABLE to your Pi executable before launching.
Open a project session. The initial session starts in your home directory. Use the folder selector or new-terminal options to create a terminal in your project directory.

Installers are unsigned unless signing is configured. Release artifacts are available, but the project does not claim every platform and live-agent scenario has been validated. Read the release notes before installing.

Run from source

Source development requires Node.js 22.19 or later (compatible with the project dependencies), npm, and a desktop environment. Native dependencies may require a C/C++ build toolchain and Python.

git clone https://github.com/adnannpm/Shumora.git
cd Shumora
npm install
npm run dev

If Pi is not found on Linux, the documented development override is:

PI_EXECUTABLE=/absolute/path/to/pi npm run dev

For Windows executable overrides and native build prerequisites, consult the repository setup instructions.

Manage independent terminal sessions

Use the plus button to open a session. Each session is its own Pi process with its own working directory. Switch tabs without stopping the sessions you leave behind.

Split right or down, resize panes, and move or merge tab groups without restarting the underlying terminals.
Reorder tabs by dragging, rename terminals, and create new sessions in a selected folder.
Stop or restart an individual process and inspect launch errors. Closing a running session requires confirmation.

A running indicator means the process is alive; it does not establish that the AI is actively working. Restarting starts a new Pi process and does not resume the previous conversation.

Discuss a decision in Council

Council brings existing Pi agents into a moderated discussion. Select at least two available, bridge-connected participants, enter a topic, optionally assign roles, and choose yourself or an agent as moderator.

The discussion runs for two rounds, with a chance for your input after each round, followed by a final summary.
You can pause, resume, stop, or take over moderation. Navigating to another app page does not interrupt the discussion.
Participants use their existing models, credentials, and session context. Each uses its own model credits.
Newly opened Shumora Pi terminals connect to the Council bridge automatically. Unconnected existing terminals are not silently restarted.

Discussion only. Tools are blocked during Council turns. Agents cannot execute commands or apply proposed changes through the discussion. Review the recommendations before separately authorizing work.

Review changes and manage integrations

Git review

The focused terminal’s working directory determines the repository shown in the workspace toolbar. Review staged and unstaged changes in a side-by-side diff; stage, unstage, discard with confirmation, commit, and manage branches.

Optional commit-message generation uses a selected model through 9router and sends the staged diff to that model. Review sensitive changes before using it.

Library

Browse Pi extensions, skills, themes, and prompts with search and filters. Package details expose supported installation, update, repair, and removal actions. Pi and 9router plugin controls manage supported global npm installations; other installation methods may need manual management. Changes can require stopping active sessions first.

9router (optional)

Pi sessions do not require 9router. If you choose to install it, Shumora exposes a local gateway dashboard with provider and model views, API-key management, health status, and managed-service logs. The local OpenAI-compatible endpoint is http://127.0.0.1:20128/v1.

Shumora only stops or restarts 9router processes it started. Externally started instances must be managed outside the app.

Know the boundaries

Session processes and workspace layouts are not automatically restored after exit. Normal shutdown stops managed Pi terminals; there is no persistent background daemon.
Terminal output replay is bounded, not a complete conversation archive.
Pi runs with your user credentials, tools, extensions, and filesystem permissions. Renderer isolation does not sandbox what the agent can do.
Installers may be unsigned. Packaging success is not proof of full runtime validation on every OS, and macOS automatic installation depends on signing configuration.
Do not treat the app as a production-hardened process supervisor. Review its security notes before using it for sensitive work.

Sources and release details

This guide reflects the repository’s v1.0.0 changelog and current source. Parts of the README still describe the earlier MVP; use versioned release notes for newly added features.

Download Shumora