Ousia

A minimalist desktop for the Pi coding agent.

Run from source  ·  Development

Ousia is a minimalist desktop for the Pi Coding Agent. It wraps Pi in a clean macOS app with project-aware sessions, streaming Markdown, and persistent chat history — so you can keep the conversation going without leaving your codebase.

Think of it as a focused GUI layer for Pi: your projects, conversations, extensions, and skills in one polished desktop workspace.

Coding agents are great in the terminal, but bouncing between your editor, terminal, and the Agent's output creates constant friction. Ousia gives Pi and its tools a dedicated desktop surface so conversations stay in context, tool invocation is visible inline, and everything persists across restarts.

• Project-first sessions — Every chat session is bound to a project directory. The agent reads, writes, and runs tools inside your project. Switch projects and the agent context follows.
• Persistent everything — Sessions, sidebar layout, window position, color theme, font preferences — all restored on relaunch.
• Streaming Markdown — Assistant responses render live with Streamdown, including fenced code blocks, tables, and expandable tool-call summaries. Watch the agent think in real time.
• Attachments in composer — Drag files and images directly into a message when your model supports multimodal input.
• Extensions & Skills — Discover, install, update, and remove Pi packages from a curated catalog, and inspect skills already available to the Agent.
• Conversation search — Search across chat history and jump directly to a matching message.
• Custom system prompts — Shape Pi's behavior with a dedicated Markdown editor for your own system instructions.
• Integrated Git branches — Create and switch project branches from the new-task flow or an active session.
• Conversation controls — Interrupt or compact a conversation, branch from an earlier message, move sessions between projects, and archive them without losing history.
• Queue or steer — Choose whether a new message waits as a follow-up or intervenes in the task the selected Agent is currently running.
• Model flexibility — Configure Pi-compatible providers (Anthropic, OpenAI, Gemini, etc.) and choose the model and thinking level for each conversation.
• Shared Pi config — Ousia reads credentials and model config from your local Pi agent directory (~/.pi/agent). Providers set up in the Pi CLI or TUI work in Ousia automatically — and vice versa.
• Local desktop state — Ousia keeps its project/session index and debug logs locally under its isolated application data and ~/.ousia/logs/.

Download the latest .dmg, open it, drag Ousia into Applications, and launch. Previous versions and release notes remain available on the Releases page.

⚠️ Ousia is pre-release software. You'll hit rough edges. We ship fast and iterate faster.

# Requirements: Node.js ≥ 24, npm ≥ 11
git clone https://github.com/s1dashu/ousia.git
cd ousia
npm install
npm start

On first launch, Ousia asks for a default workspace folder (defaults to ~/Documents/Ousia). Configure Pi providers from Settings and start a session.

The renderer talks to Pi through a narrow window.ousia IPC bridge. Electron main resolves every session's canonical project before routing the request, so renderer paths cannot expand the Agent's workspace.

┌─────────────────────────────────────┐
│  Renderer Process                   │
│  ┌──────────┐  ┌──────────────────┐ │
│  │ Sidebar  │  │     Chat         │ │
│  │ Projects │  │  ┌────────────┐  │ │
│  │ Sessions │  │  │ Streamdown │  │ │
│  │ Settings │  │  │ Tool calls │  │ │
│  └──────────┘  │  │ Composer   │  │ │
│                 │  └────────────┘  │ │
│                 └──────────────────┘ │
└──────────┬──────────────────────────┘
           │ window.ousia (IPC)
┌──────────▼──────────────────────────┐
│  Electron Main Process              │
│  ┌──────────────────────────────┐   │
│  │      Pi Agent Sessions       │   │
│  │  (canonical session +        │   │
│  │   project cwd routing)       │   │
│  └──────────────────────────────┘   │
│  ┌──────────────────────────────┐   │
│  │  App State Store (JSON)      │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘

npm run typecheck    # Type-check all TypeScript targets
npm run lint         # ESLint across the project
npm run check        # Both of the above
npx eslint src/path/to/changed-file.tsx  # Routine fast feedback
npm run verify:full  # Before commit: tests, checks, and app build

npm run package      # Production app bundle → out/
npm run make         # Local unsigned DMG (fast iteration)

# Apple Developer credentials
export APPLE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export APPLE_ID="you@example.com"
export APPLE_APP_SPECIFIC_PASSWORD="app-specific-password"
export APPLE_TEAM_ID="TEAMID"

npm run make:dmg:notarized   # Signed DMG + notarization

• Pi remains the source of truth for its providers, credentials, models, resources, and session history.
• Ousia writes desktop state atomically and keeps project/session restoration and active chat replay observable.
• Host, IPC, persistence, updater, provider, and renderer failures are recorded in structured local logs. Production builds also use privacy-sanitized Sentry diagnostics.
• Prompts, responses, tool payloads, credentials, and private file contents are excluded from diagnostics.

Contributions are welcome. Before opening a PR:

1. Read CONTRIBUTING.md and AGENTS.md
2. Run npm run check to verify types and linting
3. For packaging changes, also run npm run package
4. Keep changes aligned with the current product direction (no extensions, no workspace panels)

Ousia is MIT © 2026 Ousia Desktop contributors.

Bundled CJK fonts are under SIL OFL 1.1.

_{Built with Electron, React, and Pi. Styled with Tailwind CSS & shadcn/ui.}