Zooin Shell

A minimal desktop chat interface for operating your computer with Codex CLI or Claude Code.

Zooin Shell is built for people who know what they want their computer to do, but do not always want to remember the exact shell command. Describe the outcome in plain language, choose an engine, and let the app run the selected local CLI while keeping the result report clean and readable.

It is intentionally small: one window, one chat, clear setup, strong safety defaults.

Why Zooin Shell Exists

Command lines are powerful, but they are also unforgiving. A missing flag, a wrong path, or an overbroad delete command can waste time or damage data.

Zooin Shell aims to make everyday OS work more approachable without pretending risk does not exist:

• Plain-language requests instead of memorized command chains
• Local CLI sessions using Codex CLI or Claude Code
• No OAuth token storage inside the app
• Clear result summaries instead of noisy terminal logs
• Confirmation gates before risky actions
• Hard refusal for destructive, abusive, or unsafe requests

Highlights

• macOS-inspired minimal desktop UI
• OpenAI Codex CLI and Claude Code CLI support
• Model selection per engine
• First-run install and sign-in guidance
• English, Korean, Japanese, French, German, Spanish, and Chinese UI text
• Configurable nickname, working directory, timeout, and max action count
• Startup greeting generated only after an engine is ready
• Elapsed time shown beside completed assistant replies
• Cross-platform package builds through GitHub Actions

Quick Start

Prerequisite for development/source runs: install Node.js LTS.

Linux

npm install
npm start

Optional desktop launcher:

npm run install-linux-desktop

The launcher registers Zooin Shell in the Linux application list and adds it to GNOME favorites when available.

macOS

npm install
npm start

Login flows open in Terminal. If a Finder-launched app cannot find npm, install Node.js LTS from https://nodejs.org or Homebrew, then restart Zooin Shell.

Windows

npm install
npm start

Login flows open in Command Prompt. Zooin Shell searches common npm global paths such as %APPDATA%\npm, but restarting the app after installing Node.js is recommended.

First Launch

1. Zooin Shell checks whether Codex CLI and Claude Code CLI are installed.
2. Pick one engine.
3. Press Install if the selected engine is missing.
4. Press Sign in and complete the official CLI login flow.
5. Press Refresh.
6. Choose a model in Settings, or leave it as CLI default.
7. Start chatting.

Zooin Shell uses the selected CLI's existing login session. It does not store OAuth tokens.

If no engine is installed and signed in yet, the app shows setup first and does not generate a startup greeting. Startup greetings are generated only after the selected engine is ready.

What You Can Ask

You can ask for outcomes, checks, explanations, cleanup, setup, and local project work. Examples:

1. Show me what is taking the most disk space in my home folder.
2. Find large video files I have not opened recently.
3. Create a zip backup of my Documents folder on the Desktop.
4. Check whether Node.js, Python, Git, and Docker are installed.
5. Summarize the errors from the latest log file in this project.
6. Rename these screenshots by date and move them into a new folder.
7. Set up a simple project folder structure for a new Electron app.
8. Explain what this command would do before running it: npm run build.
9. Find duplicate filenames under Downloads and tell me before deleting anything.
10. Install the missing dependencies for this project.

For risky tasks, Zooin Shell stops and asks for confirmation. To proceed after reviewing the warning, repeat the request with 확인: at the beginning.

Safety Model

Zooin Shell adds an app-level safety layer before sending work to the selected engine.

It refuses requests intended to:

• Destroy the operating system
• Erase broad user data
• Disable security
• Steal secrets or credentials
• Evade monitoring
• Attack third parties
• Perform illegal or abusive behavior

It asks for explicit confirmation before legitimate but risky work, including:

• Deleting files
• Overwriting files
• Installing packages
• Changing permissions or ownership
• Killing processes
• Modifying system services
• Changing shell startup files
• Changing network or firewall settings
• Running remote scripts

Safety is not a guarantee. Review warnings, keep backups, and use scoped requests.

Platform Support

Platform	Runtime	Package target	Notes
Linux	Supported	AppImage, .deb	Optional GNOME launcher/favorites registration
macOS	Supported	.dmg	Public distribution should add signing and notarization
Windows	Supported	NSIS .exe	.cmd CLI execution is handled through the Windows shell

Settings

Settings include:

• Assistant nickname
• Engine
• Model
• UI and response language
• Working folder
• Timeout seconds
• Maximum action count

Defaults:

• Language: English
• Timeout: 120 seconds
• Max actions: 20
• Model: CLI default

Architecture

Zooin Shell is an Electron app with a small IPC boundary:

• src/main.js: settings, engine detection, safety checks, CLI execution
• src/preload.js: renderer-safe IPC API
• src/renderer/: chat UI, settings UI, localization
• scripts/: icon generation and Linux desktop registration

The app delegates actual AI work to the selected CLI:

• Codex: codex exec
• Claude Code: claude -p

Build

npm run prepare-icons
npm run build:linux
npm run build:win
npm run build:mac

Build outputs:

• Linux: AppImage and .deb
• Windows: NSIS installer
• macOS: .dmg

Continuous Integration

GitHub Actions builds the app on:

• ubuntu-latest
• windows-latest
• macos-latest

Artifacts are uploaded for each platform build.

Development

npm install
npm start

Useful checks:

node --check src/main.js
node --check src/preload.js
node --check src/renderer/renderer.js
npm run build:linux

Project Status

Zooin Shell is an early desktop prototype. The main flows are working, but CLI integrations can require updates when Codex CLI or Claude Code changes command behavior.

Good next steps include signed releases, screenshots, auto-update support, and more robust engine/model discovery.

Contributing

Issues and pull requests are welcome. For bug reports, include your OS, Node.js version, selected engine, and the relevant app/terminal output.

License

MIT. See LICENSE.