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 ·
English help · 한국어 도움말 ·
CodeGraph guide

Report an issue ·
Contribute

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.
4. 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 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,
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.

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 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.

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

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
for the fork and PR workflow, repository conventions, and relevant checks.

License and acknowledgements

Cheshi's original code is available under the MIT License.
Included third-party code retains its own copyright notices and license terms;
see Third-party notices.

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