deepsteve

KO | EN

gitlite — search

#javascript #python #ai #go #linux #docker #macos #windows #cli #kubernetes #awesome-list #vue #mcp #open-source

(★ 9)

A web UI for your Claude Code and Codex agents. It runs on your machine, in plain HTML, CSS and JavaScript — so your agents can build your dev tools.

deepsteve 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# deepsteve

https://deepsteve.com

A web UI for your **Claude Code** and **Codex** agents. It runs on your machine, and it's plain HTML, CSS and JavaScript — so your agents can build you a Developer Productivity Suite for each project.

Run agent sessions side-by-side in browser tabs, each a real PTY with full terminal capabilities and persistent conversation history. OpenCode, Pi, and Hermes also run, as experimental integrations — [docs/agents.md](docs/agents.md) is the per-agent breakdown of what each one actually gets.

**Runs on macOS and Linux.** The daemon is managed by a LaunchAgent on macOS and a systemd user unit on Linux; both are driven through one interface (`service.sh`). On Linux tmux is a required dependency, not optional — sessions live inside it so they survive the restarts systemd performs on every crash and upgrade.

> **Security notice:** DeepSteve is **localhost-first with token authentication**. Every surface (web UI WebSocket, MCP endpoint, REST APIs) enforces a Host allowlist, an Origin allowlist, and a per-install bearer token — closing the drive-by-webpage / DNS-rebinding hole. The browser is authenticated transparently via an HttpOnly cookie (no login screen). Auth is always on; do not expose it to an untrusted network regardless.

## Terminal Engines

deepsteve runs agent sessions (see [docs/agents.md](docs/agents.md)) inside **tmux** panes, connected to the browser via WebSocket. This is the default whenever tmux is installed, and it is what makes sessions durable: the agent belongs to the tmux server rather than to deepsteve, so it keeps working through a daemon crash, a `./restart.sh`, an auto-update, and closing the browser. Reconnecting reattaches the same live pane.

deepsteve runs its **own** tmux server, on the socket `~/.deepsteve/tmux.sock`, so its panes never mix with the ones you start yourself — `tmux ls` shows yours, `tmux -S ~/.deepsteve/tmux.sock ls` shows deepsteve's. (Set `tmuxSocket` in `~/.deepsteve/settings.json` if that path won't work, e.g. a home directory on a network filesystem.) One consequence worth knowing: **uninstalling ends deepsteve's sessions**, since removing `~/.deepsteve` would otherwise leave panes running that nothing could reach again.

Without tmux, deepsteve falls back to **node-pty**, which runs each session as a child process of the Node server. Everything works the same except durability — those sessions die with the server. The fallback is deliberately visible: the ⚙ button carries an orange dot and Settings → Terminal says which engine you are on and, if tmux wasn't found, where it looked. Install tmux to get durable sessions; if yours lives somewhere the search can't see, point the `tmuxBinary` setting at it.

## Features

- **Multiple sessions** - Open as many Claude Code or Codex instances as you need in separate tabs
- **Real terminal emulation** - PTY support via xterm.js.
- **Session persistence** - Conversations survive server restarts and page refreshes
- **GitHub issue picker** - Pick an issue from any repo and launch a session with a worktree and prompt
- **Agent coordination** - MCP tools let sessions chat, share tasks, and coordinate work
- **Runs as a daemon** - Always available in the background on your Mac
- **Themes** - Customize the UI with CSS files in `~/.deepsteve/themes/`
- **Mods** - Extend deepsteve with mods for task tracking, agent chat, browser reflection (yes, deepsteve can see itself), or [create your own](docs/mods.md)

## Quick Install

```bash
npm install -g deepsteve
deepsteve start
```

Or without npm — this one bundles its own Node if you don't have one:

```bash
curl -fsSL deepsteve.com/install.sh | bash
```

Both land the same tree in `~/.deepsteve` and register the same LaunchAgent (macOS) or systemd user unit (Linux); they differ only in where the files come from. `deepsteve start` is also the upgrade step — see [Installation (npm)](#installation-npm) for the rest of the CLI.

## Requirements

- macOS, or Linux with a systemd user instance
- Node.js — needed for `npm install -g`; the curl installer downloads its own if you have none
- tmux — **required on Linux** (both installers refuse without it), optional on macOS,
  where node-pty is a supported fallback
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex CLI](https://developers.openai.com/codex/cli/) installed — these are the two supported agents. OpenCode, Pi, and Hermes work too, but get no deepsteve MCP tools and no skills; see [docs/agents.md](docs/agents.md).

## Installation (from source)

If you've cloned the repo:

```bash
./release.sh   # generates install.sh from source files
./install.sh   # installs to ~/.deepsteve/
```

`install.sh` is gitignored — it's generated by `release.sh`, which embeds all source files as heredocs. You must run `release.sh` first.

## Installation (npm)

`npm install -g deepsteve` puts the package in npm's global prefix; `deepsteve start` is what turns it into a running install. It does what `install.sh` does: deploys the runtime into `~/.deepsteve`, registers the LaunchAgent or systemd user unit, starts the daemon, and prints the URL. The daemon runs from `~/.deepsteve` rather than from the npm package, because that directory is also where it writes — mods you install, themes, sessions and settings all live there.

| | |
|---|---|
| `deepsteve start` | deploy, register the service, start the daemon (also the upgrade step after `npm install -g deepsteve@latest`) |
| `deepsteve stop` | stop the daemon — sessions live in tmux and survive |
| `deepsteve restart` | restart, after confirming in the browser (`--force` moves the confirmation to your terminal) |
| `deepsteve status` | service state, port, health, log locations — read-only |
| `deepsteve uninstall` | remove the service, `~/.deepsteve`, and deepsteve's own tmux server |

Updating is `npm install -g deepsteve@latest && deepsteve start`. An npm install deliberately has no in-app auto-update: the package lives in a prefix deepsteve may not own, so Settings → Updates tells you the command instead of offering a button.

## Usage

Open [http://deepsteve.localhost:3000](http://deepsteve.localhost:3000) in your browser (`*.localhost` resolves to loopback; `http://localhost:3000` also works and redirects there).

- Click **+** to create a new Claude Code or Codex session in any directory
- Click the **GitHub icon** to pick an issue — deepsteve creates a worktree and starts a session with the issue as a prompt
- Right-click a tab to rename it
- Use **Shift+Enter** for multi-line input

## Command Palette

Press **⌘K** to open the command palette for quick keyboard-driven access to tabs, settings, and custom commands.

- Type to filter, arrow keys to navigate, Enter to execute
- Built-in commands: New Tab, Close Tab, Settings, Mods, Next/Previous Tab
- Switch between open tabs by name
- Customize the shortcut in Settings → Keyboard

### Custom Commands

Drop executable scripts into `~/.deepsteve/commands/` and they appear automatically in the palette:

```bash
cat > ~/.deepsteve/commands/hello.sh << 'EOF'
#!/bin/bash
echo "Hello from DeepSteve!"
EOF
chmod +x ~/.deepsteve/commands/hello.sh
```

The command name is derived from the filename (hyphens → spaces, title-cased). For custom names, add a JSON sidecar file alongside the script:

```json
// ~/.deepsteve/commands/hello.json
{ "name": "Say Hello", "description": "Prints a friendly greeting" }
```

Scripts receive environment variables: `DEEPSTEVE_SESSION_ID` (active tab's shell ID), `DEEPSTEVE_CWD` (that tab's working directory), `DEEPSTEVE_TAB_NAME`, `DEEPSTEVE_WORKTREE`, `DEEPSTEVE_WINDOW_ID`, `DEEPSTEVE_API_URL`, and `DEEPSTEVE_API_TOKEN` (send as `Authorization: Bearer $DEEPSTEVE_API_TOKEN` when calling the REST API).

## Themes

Customize the UI with CSS theme files. See the [Themes Guide](docs/themes.md) for details.

## Mods

Extend deepsteve with visual mods — alternative views, panels, and MCP tools for your sessions. See the [Mods Guide](docs/mods.md) for details.

### Skills

Skills enabled in the Mods panel are installed for Claude Code and Codex from the canonical prompts in `skills/*.md`. The experimental agents (OpenCode, Pi, Hermes) get no skills at all — enabling one in the Mods panel does nothing for those sessions.

- Claude Code: invoke `chat.md` as `/deepsteve:chat`, with any arguments after the slash command.
- Codex: mention the generated skill as `$deepsteve-chat`, with any arguments after the mention.

DeepSteve keeps Claude command copies under `~/.claude/commands/deepsteve` and exposes Codex-compatible `SKILL.md` folders through managed symlinks under `~/.agents/skills`. Existing non-symlink paths there are left untouched.

## Custom Model Providers (OpenRouter)

Claude Code sessions can run against any Anthropic-compatible API endpoint — OpenRouter, a corporate gateway, a local proxy — using a **custom Claude config profile**. No mod or proxy needed; each profile is just a separate `CLAUDE_CONFIG_DIR` with its own provider env, and tabs opt into it per session.

Example: running [GLM 5.2](https://openrouter.ai/z-ai/glm-5.2) through OpenRouter.

**1. Create a config directory** with a `settings.json` that points Claude Code at the provider:

```bash
mkdir ~/.claude-open-router
cat > ~/.claude-open-router/settings.json <<'EOF'
{
 "env": {
 "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
 "ANTHROPIC_AUTH_TOKEN": "sk-or-v1-YOUR-OPENROUTER-KEY",
 "ANTHROPIC_API_KEY": "sk-or-v1-YOUR-OPENROUTER-KEY",
 "ANTHROPIC_MODEL": "z-ai/glm-5.2",
 "ANTHROPIC_SMALL_FAST_MODEL": "anthropic/claude-haiku-4.5",
 "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-4.8",
 "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-5",
 "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5"
 },
 "model": "z-ai/glm-5.2"
}
EOF
```

`ANTHROPIC_MODEL`/`model` pick the main model by the provider's id; the `ANTHROPIC_DEFAULT_*`/`SMALL_FAST` entries map Claude Code's internal model tiers to provider ids so background/fast paths keep working.

**2. Register it in deepsteve**: Settings → **Custom Claude configs** → add a row with a display name (e.g. `OpenRouter`) and the config dir (`~/.claude-open-router`).

**3. Open a tab with it**: the profile appears alongside the agents in the new-tab menu. Sessions started with it spawn Claude Code with `CLAUDE_CONFIG_DIR` pointing at that directory — provider, model, auth, and conversation history all stay isolated per profile, and regular Claude tabs are unaffected.

Note: plain base-URL routing covers normal use. OpenRouter-specific request-body fields (e.g. pinning a backend `provider`) aren't expressible this way — that was proposed as a transform-proxy mod in #499 and closed as not needed in practice.

## Managing the Daemon

```bash
./restart.sh            # restart (browser tabs silently reconnect)
./restart.sh --refresh  # restart + force browser reload
./status.sh             # is it running, on what port, where are the logs?
```

`./status.sh` is read-only and safe to allowlist; `./restart.sh` is not. Both work the
same on either platform — `service.sh` is the single interface over launchd and the
systemd user unit, so nothing above needs a platform-specific variant.

Logs:

| | |
|---|---|
| macOS | `~/Library/Logs/deepsteve.log` |
| Linux | `~/.local/share/deepsteve/logs/deepsteve.log` |

(`./status.sh` prints the right one for this machine, along with the service state and,
on Linux, whether user lingering is enabled — without it the daemon stops when your last
login session ends and does not start at boot.)

## Security

- Serves `http://deepsteve.localhost:3000` on loopback only by default — not accessible from the network. `--bind <address>` widens that, and logs a warning banner when it does.
- **Token-authenticated** on every surface (WebSocket, MCP, REST): a Host allowlist + Origin allowlist + a per-install secret at `~/.deepsteve/auth-token` (`0600`) close the cross-origin / DNS-rebinding hole. The browser gets the token as an HttpOnly cookie; other clients send it as `Authorization: Bearer <token>`. Widen access with `--allow-origin` / `--allow-host`.
- The UI lives on **`http://deepsteve.localhost:3000`** — still loopback-only (RFC 6761), but with its own browser cookie jar so the auth cookie can't be evicted when other local dev apps fill the shared `localhost` jar. Browser navigations to `localhost:3000` get a 302 there; disable with `--no-canonical-redirect` (or `DEEPSTEVE_NO_CANONICAL_REDIRECT=1`) if `*.localhost` doesn't resolve on your system.
- Each agent session runs with the permissions of the user who installed deepsteve

## Running on Meta Quest (WebXR)

WebXR requires a secure context (HTTPS). DeepSteve has built-in HTTPS support for this:

1. Start the server with HTTPS enabled, bound to all interfaces:

```bash
cd ~/.deepsteve && node server.js --bind 0.0.0.0 --https
```

2. Navigate to `https://<your-laptop-ip>:3443` on the Quest browser. The server logs will show the exact URL to use.

3. On first connect you'll see a certificate warning — accept it to proceed. (Install [mkcert](https://github.com/FiloSottile/mkcert) on your laptop for locally-trusted certificates with no warnings.)

Certificates are auto-generated at startup and stored in `~/.deepsteve/certs/`. They regenerate automatically when your LAN IP changes.

## Contributing

Bug reports and feature requests are welcome on [GitHub Issues](https://github.com/deepsteve/deepsteve/issues). Pull requests are welcome.

## Uninstall

```bash
~/.deepsteve/uninstall.sh
```

deepsteve

deepsteve 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

deepsteve

deepsteve 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README