## How to run typescript cli

Required: [Bun](https://bun.sh) >= 1.0, Node >= 20

### Dev mode

`cd cortexagent/codingagent/coco`

`bun install`

`bun run dev`

To enable experimental skills (e.g., verification-skill):

`CORTEX_ENABLE_EXPERIMENTAL_SKILLS=1 bun run dev`

To enable legacy streaming mode (assistant text streams live instead of buffered):

`CORTEX_CODE_STREAMING=true bun run dev`

### Build mode

`cd <>/coco`

`bun run build`

`bun dist/index.js`

<p>Note: with build mode you can provide params such as </p>

`bun dist/index.js --help`

`bun dist/index.js --output-format stream-json`

## Desktop launcher

The repo now includes a tray-only Tauri launcher under `desktop/` plus a bundled Bun sidecar backend.

For the full install and setup flow, see [Desktop Install And Setup](docs/DESKTOP_INSTALL_AND_SETUP.md).

### Developer setup

`bun install`

`npm --prefix desktop install`

### Build assets and sidecar

`bun run desktop:prepare`

This does three things:

- builds the static `web/` export
- builds the Bun sidecar binary
- copies the web export into the desktop bundle resources

### Run the launcher locally

`bun run desktop:dev`

### Build packaged app artifacts

Debug:

`bun run desktop:build:debug`

Release:

`bun run desktop:build`

### Install the built macOS app

Build the release app, then copy it into `/Applications`:

```bash
cortex create-ui-launcher
```

Manual equivalent:

```bash
bun run desktop:prepare
bun run desktop:build
ditto desktop/src-tauri/target/release/bundle/macos/Cortex.app /Applications/Cortex.app
open /Applications/Cortex.app
```

End users only need `Cortex.app`. They do not need Bun, Node, or Terminal.

### Smoke test the local packaged backend path

`bun run desktop:smoke`

## UI mode (`--ui`)

Run cortex as a local WebSocket backend:

`bun run dev -- --ui`

When `--ui` is used, Cortex also auto-starts the local `web/` Next.js dev server
if present. Set `CORTEX_UI_AUTO_WEB=0` to disable auto-start.

Default endpoints:

- WebSocket: `ws://127.0.0.1:4242/ws`
- Health: `http://127.0.0.1:4242/healthz`

Optional env overrides:

- `CORTEX_UI_HOST`
- `CORTEX_UI_PORT`
- `CORTEX_UI_WEB_DIR`
- `CORTEX_UI_AUTO_WEB`

### Web frontend (Next.js)

`cd web`

`npm install`

`npm run dev`

Set `NEXT_PUBLIC_CORTEX_WS_URL` if your backend URL differs from the default.

## Desktop launcher URL behavior

- Preferred browser URL: `http://cortex.localhost:1355/`
- Fallback browser URL: `http://127.0.0.1:1355/`
- Packaged backend bind address: `127.0.0.1:1355`
- Menu actions:
  - Open Cortex
  - Open Direct URL
  - Restart Cortex
  - View Logs
  - Quit

## Troubleshooting

### macOS keychain prompts

If you're getting repeated macOS keychain password dialogs, run:

```
./scripts/reset_keychain.sh
```

This deletes all Cortex keychain entries. You'll re-authenticate to Snowflake on the next launch.

## Documentation

- [Desktop Install And Setup](docs/DESKTOP_INSTALL_AND_SETUP.md) - End-user install steps, developer setup, logs, and troubleshooting
- [Desktop Launcher Architecture](docs/DESKTOP_LAUNCHER_ARCHITECTURE.md) - Packaged launcher/sidecar design and URL behavior
- [Sandbox Design](docs/SANDBOX_DESIGN.md) - Isolated command execution architecture
