<div align="center">

<img src="assets/banner.png" alt="otherside cli" width="720">

![status](https://img.shields.io/badge/status-0.3--pre-EC4899?style=for-the-badge&labelColor=1a1a2e)
![typescript](https://img.shields.io/badge/typescript-5+-51158C?style=for-the-badge&logo=typescript&logoColor=white&labelColor=1a1a2e)
![license](https://img.shields.io/badge/license-MIT-51158C?style=for-the-badge&labelColor=1a1a2e)

<img src="assets/demo.gif" alt="otherside demo" width="720">

### _a shell for the reversed world._
FREE-first Claude Code-style terminal coding agent. Multi-provider: Anthropic, Codex, Antigravity (Gemini/Claude), Vertex, Kimi, DeepSeek or self-hosted LLMs.

**Privacy. Control. No hidden throttles. Versatility. Economy.**

<a href="https://apps.apple.com/app/id6769261609"><img src="assets/app-store.svg" alt="App Store" height="40"></a>
<a href="https://play.google.com/store/apps/details?id=dunamis.otherside"><img src="assets/google-play.svg" alt="Google Play" height="40"></a>

[**Overview**](#overview) · [**Ahead of the curve**](#ahead-of-the-curve) · [**Features**](#features) · [**Install**](#installation) · [**Build**](#build-from-source) · [**Operation**](#operation) · [**Providers**](#providers) · [**Contributing**](#contributing)

</div>

> [!WARNING]
> **Pre-release software.** Otherside is under active development. Expect bugs, rough edges, and breaking changes.

## Overview

Otherside gives you Claude Code-style AI coding power with multiple providers.

Start **TOTALLY FREE** with a Google account through the built-in Antigravity provider, add local LLMs through any OpenAI-compatible endpoint, and combine them with Anthropic, Codex, Vertex, Kimi, and DeepSeek in the same workflow. Otherside searches real codebases, edits files, runs commands, verifies results, generates images with Codex, gives even text-only providers the ability to read images via a novel vision side-channel, and keeps the same tools and sessions across providers.

Everything important is built in: provider auth, model switching, persistent sessions, bridge mode, permissions, and diffs. No telemetry, no vendor lock-in, fewer restrictive rails, and full control over where your code goes.

Otherside keeps evolving with battle-tested tools, workflows, and best practices for coding, cybersecurity, infrastructure, automation, and other high-leverage terminal workflows.

## Ahead of the curve

Here are some of the next-wave features we added to push your work further: companion mobile app integration, FREE provider paths, local LLMs, intelligent memory, goal-driven execution, image generation and parsing, and terminal-native tools designed for high-leverage coding sessions.

- **Remote session via app**: pair your terminal session with the companion iOS/Android app to monitor progress, read live logs, and interact with the agent on the go.
- **Image generation via Codex**: `GenerateImage` calls Codex's hosted image tool to produce 1024x1024 / 1536x1024 / 1024x1536 PNGs straight from a prompt. Optional transparent backdrop with chroma-key alpha matting for clean compositing.
- **Vision side-channel for blind providers**: novel `ParseImage` tool (and the `Read` tool on `.png` / `.jpg`) gives DeepSeek and other text-only models the ability to "see". Pasted screenshots, on-disk images, and UI mockups are routed through a configurable vision provider behind the scenes; the calling model gets a text description and can reason about the image as if it had native vision support.
- **Goal guardrails**: set a success condition with `/goal` and keep the agent working until the outcome is actually approved. Stop-hook classifier resumes the mission across autocompact boundaries.
- **Dream memory consolidation**: run `/dream` to distill recent work into structured project memory, keeping long-running context useful across sessions.
- **Optimized system prompt**: a cleaner prompt stack with fewer useless rails and artificial limitations, tuned for work quality, deeper reasoning, and better tool use instead of vendor-side convenience.
- **FREE Google access**: start with a Google account and use strong coding models through Google OAuth with Antigravity.
- **Provider combinations**: blend FREE, local, and hosted models in one workflow instead of betting everything on one backend.
- **Live wallet & quota**: `/usage` shows weekly/5h limits for Kimi, USD wallet balance for DeepSeek, plan utilization for Anthropic / Codex / Antigravity, and a provider switcher to hop between accounts without leaving the panel.
- **Security-ready workflows**: code review, security review, and deep repository audits built directly into the terminal agent.
- **Bridge mode preview**: OpenAI-compatible serving is taking shape for external tools, custom integrations, and agent chains.

## Features

| | |
| --- | --- |
| **Complete native toolset** | Built-in shell, search, web, read, edit, write, image-generate, and image-parse tools for real work inside real codebases. The agent acts, verifies, and reports; it doesn't just suggest. |
| **One workflow, many providers** | Built-in support for Anthropic, Codex, Gemini, Antigravity, Vertex, Kimi, DeepSeek, and any OpenAI-compatible endpoint. Combine FREE Google paths, local LLMs, and hosted providers without rebuilding your setup. |
| **Remote session via app** | Pair your terminal session with the companion iOS/Android app over an end-to-end encrypted channel brokered by Supabase. Watch sessions, read live logs, and interact with the agent from your phone. |
| **Goal-driven execution** | Set success criteria with `/goal` and keep the agent autonomously running/retrying across autocompact boundaries until the outcome is met and approved. |
| **Background tasks & shells** | Spawn and manage long-running background tasks (`/tasks`) and parallel terminal shell sessions (`/bashes`) directly from the agent interface. |
| **State checkpoints** | Easily restore code changes and conversation history to any previous checkpoint or turn using the `/rewind` command. |
| **MCP server integration** | Connect external tools, databases, and APIs using the Model Context Protocol (`/mcp` command) to extend the agent's capabilities. |
| **Image generation (Codex)** | `GenerateImage` produces 1024x1024 / 1536x1024 / 1024x1536 PNGs through Codex's hosted image tool. Optional transparent output with chroma-key alpha matting (Chebyshev distance + smoothstep ramp + dominance check + despill + min-filter + Gaussian blur) to drop the backdrop cleanly. |
| **Vision for blind providers** | Novel side-channel: `ParseImage` and the `Read` tool route screenshots, diagrams, and UI mockups through a configurable vision provider behind the scenes — even text-only models like DeepSeek can reason about pasted images as if they had native vision. |
| **Persistent project memory** | `/dream` turns recent work into structured memory so Otherside can carry useful context across sessions instead of starting cold every time. |
| **Live usage & wallet** | `/usage` aggregates per-session and all-time totals across providers; shows Kimi weekly/5h limits, DeepSeek USD wallet, Anthropic/Codex/Gemini/Antigravity plan utilization, and lets you hop between accounts without leaving the panel. |
| **Zero-telemetry control** | No product analytics, no hidden relay, no background tracking. Your code goes from your machine to the provider you choose, with no hidden throttles or surprise limits added without your consent. |
| **Single-binary install** | One lightweight executable to install, launch, and carry between projects. No heavyweight app stack required. |
| **Bridge mode** ⚠️ | **[in progress]** `otherside serve` exposes `/v1/chat/completions` so external tools can drive the same loop. |

## Installation

Install uses the published release binary. You do not need Bun, Node, or a source checkout.

### macOS

```bash
curl -fsSL https://othersidecli.com/install.sh | bash
```

- Supports Apple Silicon and Intel Macs.
- Installs `otherside` to `~/.local/bin` by default.
- If the command is not found after install, add this to `~/.zshrc` or `~/.bashrc`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

### Linux

```bash
curl -fsSL https://othersidecli.com/install.sh | bash
```

- Supports x64 and arm64 Linux.
- Requires `curl`, `uname`, `mkdir`, and `install`.
- Verifies the release checksum when `sha256sum` or `shasum` is available.
- If `~/.local/bin` is not on your `PATH`, add it to your shell rc:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

### Windows

Run in PowerShell:

```powershell
irm https://othersidecli.com/install.ps1 | iex
```

- Supports 64-bit Windows x64.
- Installs `otherside.exe` to `%LOCALAPPDATA%\Programs\otherside`.
- Adds the install directory to the user `Path`; restart PowerShell, Windows Terminal, or your IDE terminal after install.
- Git for Windows is recommended so shell commands can use Git Bash semantics when needed.
- Image resizing uses ImageMagick when installed:

```powershell
winget install ImageMagick.ImageMagick
```

### Install options

Pin a release:

```bash
OTHERSIDE_VERSION=v0.3.0-pre bash -c "$(curl -fsSL https://othersidecli.com/install.sh)"
```

```powershell
$env:OTHERSIDE_VERSION = "v0.3.0-pre"
irm https://othersidecli.com/install.ps1 | iex
```

Install somewhere else:

```bash
OTHERSIDE_INSTALL_DIR=/usr/local/bin bash -c "$(curl -fsSL https://othersidecli.com/install.sh)"
```

```powershell
$env:OTHERSIDE_INSTALL_DIR = "$env:USERPROFILE\bin"
irm https://othersidecli.com/install.ps1 | iex
```

### Verify and launch

```bash
otherside --version
otherside
```

First run walks you through provider login.

## Build from source

Build from source is for contributors or local changes. It requires Bun 1.3+ and creates a local binary from your checkout.

```bash
git clone https://github.com/daanielcruz/otherside-cli.git
cd otherside-cli
bun install --frozen-lockfile
bun run build
./dist/otherside --version
```

`bun run build` writes `./dist/otherside` for the current configured target. The repository default targets macOS arm64 because local development happens there; releases are cross-built by CI for macOS, Linux, and Windows.

To install your locally built binary on macOS or Linux:

```bash
mkdir -p "$HOME/.local/bin"
cp ./dist/otherside "$HOME/.local/bin/otherside"
chmod +x "$HOME/.local/bin/otherside"
```

Or use the helper:

```bash
bun run build:install
```

On Windows, build with an explicit Windows target and copy the executable to your chosen install directory:

```powershell
bun build --compile --target=bun-windows-x64 --outfile=dist/otherside.exe src/main.ts
$InstallDir = "$env:LOCALAPPDATA\Programs\otherside"
New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
Copy-Item .\dist\otherside.exe "$InstallDir\otherside.exe" -Force
```

Contributor checks:

```bash
bun run typecheck
bun run lint
bun run test
```

## Operation

Three modes share the same harness.

```bash
# Interactive TUI (default)
otherside

# Resume a saved session for the current project
otherside --resume <session-id>
otherside -c   # most recent session in this cwd

# One-shot run (scripts, CI, cron)
otherside -p "refactor the session loader to use the shared path helper"

# Pipe stdin
cat logs.txt | otherside -p "find the stack trace that caused the segfault"

# OpenAI-compatible bridge preview on port 8080
otherside serve --port 8080

# Skip every permission prompt
otherside --yolo
```

## Providers

Each provider carries its own auth, wire fingerprint, tool adaptation, and model catalog behind a single interface.

```bash
otherside --provider deepseek
otherside --provider codex --model gpt-5.5
otherside --provider openai-custom --model <your-model>
```

| Provider | Slug | Auth | Notes |
|---|---|---|---|
| Anthropic | `anthropic` | OAuth | Subscription plan support, web-search, plan/usage panels. |
| Codex | `codex` | OAuth | GPT-5.x line, hosted image generation, websocket `/responses`. |
| Antigravity | `antigravity` | OAuth | Free Google account path, Gemini 3 Pro/Flash + Claude Sonnet/Opus + multi-account quotas. |
| Vertex | `vertex` | API Key / OAuth | GCP project — pay-as-you-go via Cloud Billing. Gemini models supported. |
| Kimi | `kimi-code` | API Key | Kimi-k2.6 Thinking, weekly + 5h limits in `/usage`. |
| DeepSeek | `deepseek` | API Key | DeepSeek V4 Pro, USD wallet visible in `/usage`. Gains image-read ability via the vision side-channel even though the underlying API has no native vision support. |
| OpenAI Custom | `openai-custom` | API Key | Any OpenAI-compatible endpoint (LM Studio, llama.cpp, vLLM, TGI, custom). |

Login per provider:

```bash
otherside login          # pick from the list
otherside login deepseek # target a specific provider
otherside logout deepseek
```

`openai-custom` works with any OpenAI-compatible endpoint: LM Studio, llama.cpp, vLLM, Hugging Face TGI, or any self-hosted runtime.

### Important — Antigravity

Otherside ships **carefully crafted wire fingerprints** for `antigravity` that emulate the official Google clients. Using this provider through any third-party client (otherside included) **may violate Google's Terms of Service**. Recommended:

- Treat `antigravity` as a **best-effort, use-at-your-own-risk** path.
- Prefer **secondary Google accounts**, not your primary one.
- Google may revoke access, throttle, or terminate accounts at its discretion.

You assume the risk when enabling this provider.

## Contributing

Clean-room TypeScript + Bun. PRs welcome.

See [Build from source](#build-from-source) for setup and local build commands. Requires Bun 1.3+.

## Star history

<a href="https://www.star-history.com/?repos=daanielcruz%2Fotherside-cli&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=daanielcruz/otherside-cli&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=daanielcruz/otherside-cli&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=daanielcruz/otherside-cli&type=date&legend=top-left" />
 </picture>
</a>

<sub>Every CLI has two sides. You're looking at one of them.</sub>
