Open Source / Built at OpenAI HQ / macOS

Codex superpowers
for everyone

Stash is a macOS overlay where you drop anything related to a project. Under the hood, it spins up a sidekick team of agents in parallel isolated worktrees -- one investigates, one drafts, one fixes, one produces concrete artifacts like docs, CSVs, or scripts.

Scroll to explore

Features

/ What Stash implements today

01

Workspace + Overlay

Codex-style light-mode desktop layout with project picker, 3-pane explorer/workspace/chat, and a floating overlay -- both native SwiftUI

UI
02

Local File Indexing

Background watcher triggers incremental re-index on file changes. Local hashed-embedding vector search with zero cloud dependency

Index
03

Run Orchestration

Planning, execution, and confirmation phases via Codex CLI in isolated worktrees. Apply or discard proposed filesystem changes with one click

Runs
04

@file Mentions & Composer

Type @ in the composer to attach project files as structured context parts. Optimistic messages appear instantly while runs execute

Context
05

Quick Actions & AI Setup

Context-aware empty-chat suggestions refined by indexing. Configure planner backend, Codex CLI model, and optional OpenAI API fallback in-app

Config
06

Project Portability

All state in PROJECT_ROOT/.stash/ -- SQLite DB, vector index, skills, worktrees, and logs. Resume on any machine by opening the folder

Local

Workflow

/ From clone to code execution

01

Install & Launch

Clone the repo, run install_stack.sh to provision the Python venv with FastAPI and tooling, then run_backend.sh to start the local service on 127.0.0.1:8765. Or use run_everything.sh for a single command.

02

Open a Project

Pick any folder in the workspace app or overlay. Stash creates .stash/ inside it with SQLite DB, project config, skills, and worktrees. Background indexing and file watching start automatically.

03

Chat & Mention

Describe work in the composer. Type @ to attach project files as structured context. Quick actions suggest prompts refined by indexed content. Your messages appear instantly via optimistic rendering.

04

Plan, Execute, Confirm

The planner breaks your request into steps using Codex CLI or OpenAI API fallback. Each step executes in an isolated worktree. Review the live todo list, then apply or discard filesystem changes.

Two apps,
one backend,
zero cloud

The FastAPI backend on 127.0.0.1:8765 is the source of truth for all project state -- SQLite conversations, vector index, file watcher, and Codex CLI orchestration. Both the workspace app and overlay are thin SwiftUI clients that sync through it via HTTP and SSE.

The backend never auto-runs sudo. It checks read/write permissions on project open and blocks write operations on read-only folders with clear remediation hints. Everything lives inside PROJECT_ROOT/.stash/ -- copy the folder to resume on any machine.

backend-service/
FastAPI + SQLite
HTTP & SSE API, vector index, file watcher, Codex CLI runner, quick-actions endpoint
frontend-macos/
SwiftUI Package
StashMacOSApp (3-pane workspace) and StashOverlay (floating), VS Code-like tab system
.stash/
Per-Project State
stash.db, project.json, indexing/execution skills, worktrees, logs -- fully portable
scripts/
Install & Run Helpers
install_stack.sh, run_backend.sh, run_everything.sh, desktop installer, test runners

Quick
Start

/ Open source, MIT license, built in public

Repository
github.com/setrf/stash
Prerequisites

macOS 14+, Python 3.11+, Swift in PATH

Xcode Command Line Tools required: xcode-select --install

GitHubBackend DocsFrontend DocsDesktop Installer

Quick Start

$

git clone https://github.com/setrf/stash && cd stash

$

./scripts/install_stack.sh

$

./scripts/run_everything.sh

Or install as a desktop app:

$

./scripts/desktop/install_desktop_app.sh

$

open "$HOME/Desktop/Stash Local.app"

Tech Stack

SwiftUIPython 3.11+FastAPISQLiteCodex CLISSE StreamingVector SearchmacOS 14+Worktree Isolation