Cheshi

Cheshi

A desktop workspace for AI-assisted development. Work with Codex, explore your codebase with CodeGraph, and manage code, terminals, and Git in one place.

Releases · [Changelog](CHANGELOG.md) · [English help](.docs/help/en/) · [한국어 도움말](.docs/help/ko/) · [CodeGraph guide](.docs/codegraph/guide.md)

Report an issue · [Contribute](CONTRIBUTING.md)

Cheshi is in preview. Install it through the Cheshi Homebrew Tap, or download the signed and notarized ZIP from Releases.

Install with Homebrew

The first packaged release requires Apple Silicon and macOS Tahoe 26 or later because its bundled CodeGraph executables require macOS 26. Install Homebrew if it is not already available, then run:

brew install --cask cheshiai/tap/cheshi

This installs Cheshi into Applications. The Cask declares GitHub CLI (gh) and Codex CLI (codex) as dependencies, so Homebrew installs them when they are not already registered with Homebrew. If you installed either CLI through another package manager, check for an existing installation conflict.

First launch

1. Open Cheshi from Applications.
2. Follow the Codex sign-in prompt if needed. Installation does not sign you in.
3. In Workspaces, open a local folder, create a project, or clone a repository.

Sign in to GitHub when prompted for GitHub features.

1. Cheshi creates the workspace's initial CodeGraph index automatically. Once

indexing completes, explore the code graph or ask Codex about the project.

CodeGraph is included and configured by Cheshi. You do not need a separate CodeGraph installation, environment variables, or manual MCP registration to use it inside the app. Cheshi connects its bundled CodeGraph runtime to the selected workspace and the same index used by the viewer.

Workspace registrations and indexes are stored under ~/Library/Application Support/Cheshi/, outside your project. There is no need to create ~/.codegraph or a .codegraph folder in the repository.

The [CodeGraph CLI](#codegraph-cli) instructions below are optional developer tools; they are not installation steps for the desktop app.

Update

Use Cheshi's update notification when a newer release is available. To update through Homebrew instead, quit Cheshi and run:

brew update
brew upgrade --cask --greedy cheshiai/tap/cheshi

--greedy includes casks marked as supporting in-app updates.

Features

• AI conversations: work with Codex, attach files, revisit conversations,

and use temporary chats for separate tasks.

• Code exploration: use local CodeGraph indexes to search symbols, inspect

relationships, and follow callers and callees.

• Editing: edit project files with language support and inspect changes

through local history.

• Terminal: use the embedded Ghostty terminal with split panes on macOS.
• Git and projects: open or clone repositories, review diffs, and manage

branches and workspaces.

CodeGraph indexes are stored locally, outside your source repositories. AI conversations use the configured provider and its authentication; local indexing does not mean AI requests run offline.

Previous conversation recall is off by default, including for existing TypeSafe key holders. Enable Settings → TypeSafe API → Allow history recall and reopen the workspace to expose the tools. Saving a key alone does not enable recall. This setting applies to all workspaces, including ones opened later. Each search stays within the workspace where it is requested. When enabled, the assistant can send the search question, candidate passages, titles and neighboring messages from this workspace's conversations to TypeSafe (Jev). If Jev is unavailable or no key is configured, OpenAI (Luna low) evaluates the same search material using your Codex login. Retrieved originals return to the assistant. Turning recall off cancels pending recall in all workspaces and blocks both providers; it cannot undo transmissions already made. Local history browsing remains available.

Jev also supports yes/no decisions in explicitly invoked [executable skills](.docs/skill-flow/guide.md), with Luna low fallback. That runner is currently a source-checkout CLI feature, separate from the history recall switch. Jev usage and fixed-sample connection checks use your TypeSafe account allowance; Luna uses your Codex account.

Run from source

The current native terminal integration targets macOS. Development requires:

• Bun 1.3.14 or newer and Git.
• Node.js with native TypeScript stripping support for the desktop scripts.
• Full Xcode with its command-line tools selected, including Swift 6.0 or newer,

for the macOS terminal bridge.

• Codex CLI for AI conversations. The app guides you through its setup and login.
• GitHub CLI (gh) for GitHub account and repository features.

git clone https://github.com/CheshiAI/Cheshi.git
cd Cheshi
bun install
bun run desktop:dev

The first macOS run builds the native terminal bridge and downloads its pinned Swift dependencies. Later runs reuse the build when its inputs are unchanged. The development process reloads the renderer and restarts desktop services as needed when source files change.

To open a particular project:

CHESHI_WORKSPACE=/absolute/path/to/your/project bun run desktop:dev

TypeScript/JavaScript, Python, and Rust language servers are detected by the app. Packaged builds include the TypeScript server and Pyright; Rust support uses an installed rust-analyzer. If a server is unavailable, parser-only support is used.

CodeGraph CLI

Use the CLI from the checkout without a global installation:

bun run cheshi-cli --help
bun run cheshi-cli codegraph --help
bun run cheshi-cli codegraph status /absolute/path/to/your/project --json

For indexing, search, graph queries, and MCP setup, see the [CodeGraph guide](.docs/codegraph/guide.md).

The optional native extraction kernel requires Rust and a C/C++ toolchain:

bun run --cwd codegraph build:kernel

Without this kernel, extraction uses the bundled WebAssembly grammars.

Build and validate

Run commands from the repository root:

bun run typecheck
bun run test
bun run viewer:build

The full development check also validates the desktop entry points and preload:

bun run check

To package the desktop application or make a ZIP distribution for the host platform and architecture:

bun run desktop:package
bun run desktop:make

Packaging outputs are written under out/. These commands build local artifacts; publishing releases and signing distribution builds are separate steps.

Configuration and local data

[.env.product](.env.product) contains public app branding and version metadata. Keep credentials out of this file and out of Git. Local environment files and build outputs are excluded by [.gitignore](.gitignore).

On macOS, workspace registrations, settings, and CodeGraph indexes use ~/Library/Application Support/Cheshi/. Opening a workspace without an index starts its initial indexing. Existing indexes are reused.

Project layout

| Path | Purpose | | --- | --- | | cli/ | Public Cheshi CLI | | codegraph/ | Local indexing, extraction, graph queries, and MCP engine | | desktop/main.mts, desktop/lib/ | Electron lifecycle and desktop services | | desktop/preload.cts, desktop/shared/ | Desktop bridge and shared contracts | | desktop/frontend/ | React interface and shared controls | | desktop/backend/ | CodeGraph service and runtime host | | desktop/native/ | Native terminal integration | | config/, scripts/, forge.config.mts | Product configuration and build tools | | .docs/ | User help and developer guides |

Contributing

Bug reports, feature ideas, and focused pull requests are welcome in English or Korean. Use GitHub Issues to report a problem or suggest an improvement. See [CONTRIBUTING.md](CONTRIBUTING.md) for the fork and PR workflow, repository conventions, and relevant checks.

License and acknowledgements

Cheshi's original code is available under the [MIT License](LICENSE). Included third-party code retains its own copyright notices and license terms; see [Third-party notices](THIRDPARTYNOTICES.md).

Cheshi builds on CodeGraph by Colby Mchenry, Electron, Ghostty, Tree-sitter, CodeMirror, and other open-source projects.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CheshiAI
• Source: CheshiAI/Cheshi
• License: MIT
• Homepage: https://github.com/CheshiAI/Cheshi/releases/latest

Install and usage instructions live in the source repository linked above.