Metadata-Version: 2.4
Name: twicc
Version: 1.7.1
Summary: Claude Code and Codex Web UI
Project-URL: Homepage, https://github.com/twidi/twicc
Project-URL: Repository, https://github.com/twidi/twicc
Project-URL: Releases, https://github.com/twidi/twicc/releases
Project-URL: Bug Tracker, https://github.com/twidi/twicc/issues
Author-email: Stéphane 'Twidi' Angel <s.angel@twidi.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.13
Requires-Dist: blacknoise~=1.2.0
Requires-Dist: channels~=4.3.2
Requires-Dist: claude-agent-sdk==0.2.91
Requires-Dist: cronsim~=2.7
Requires-Dist: daphne~=4.2.1
Requires-Dist: django~=6.0.4
Requires-Dist: httpx~=0.28.1
Requires-Dist: json-repair~=0.59.5
Requires-Dist: keyring~=25.7.0; sys_platform == 'darwin'
Requires-Dist: openai-codex-cli-bin==0.136.0
Requires-Dist: orjson~=3.11.8
Requires-Dist: pillow>=12.2.0
Requires-Dist: psutil~=7.2.2
Requires-Dist: pydantic>=2.12
Requires-Dist: python-dotenv~=1.2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: tantivy~=0.25.1
Requires-Dist: typer~=0.24.1
Requires-Dist: uvicorn~=0.44.0
Requires-Dist: watchfiles~=1.1.1
Requires-Dist: websockets~=16.0
Requires-Dist: xmltodict~=1.0.4
Provides-Extra: test
Requires-Dist: pytest-django>=4.8.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# TwiCC

> **T**he **W**eb **I**nterface for **C**laude and **C**odex

A single self-hosted web interface for both [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic) and [Codex](https://openai.com/codex/) (OpenAI). Browse projects and sessions, run agents, follow them in real time, track costs and quotas, and stay in control of your AI coding work — from desktop or mobile, in your browser.

![TwiCC screenshot](https://raw.githubusercontent.com/twidi/twicc/main/frontend/public/screenshots/session-example.webp)

[![Crafted with love](https://img.shields.io/badge/crafted_with-love-red?style=social&logo=githubsponsors&logoColor=red)](https://github.com/sponsors/twidi)
[![PyPI version](https://img.shields.io/pypi/v/twicc?logo=pypi&logoColor=blue&style=social)](https://pypi.org/project/twicc/)
[![Python versions](https://img.shields.io/pypi/pyversions/twicc?logo=pypi&logoColor=blue&style=social)](https://pypi.org/project/twicc/)
[![GitHub license](https://img.shields.io/github/license/twidi/twicc?logo=github&style=social)](https://github.com/twidi/twicc/blob/main/LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/twidi/twicc?logo=github&style=social)](https://github.com/twidi/twicc/releases)
[![Twitter](https://img.shields.io/badge/Twitter-Twidi-blue?style=social&logo=x&logoColor=blue)](https://x.com/twidi)

## Disclaimer

This is a personal project made by Twidi for his own needs. It is freely available and you are welcome to use it however you see fit.

That said, **no support is guaranteed**. Suggestions, issues, and pull requests are welcome, but there is no commitment to address them.

Note: the project was almost entirely vibe-coded, with general oversight from the author.

## Quick start

```bash
uvx twicc@latest
```

Then open <http://localhost:3500>.

> **Don't have `uvx`?** It comes with [uv](https://docs.astral.sh/uv/), a fast Python package manager:
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```
> A plain `pip install twicc` in your own virtualenv also works.

### Permanent install

If you use TwiCC regularly, install it as a persistent tool:

```bash
uv tool install twicc
twicc
```

Update with:

```bash
uv tool upgrade twicc
```

## Features

### Claude Code and Codex, side by side

- **Both providers in one UI**, using your existing credentials — nothing extra to set up
- Live conversation with full tool-use details, real-time streaming of assistant text and thinking
- Per-session agent control: model (Opus 4.8, Sonnet 4.6, …), context window (200K / 1M), effort, thinking, fast mode, permissions (including Claude Code's classifier-gated "auto" mode), with reusable presets
- Interactive tool approvals and provider questions, answered directly from the browser
- **Persistent Claude Code cron jobs**: scheduled tasks survive TwiCC restarts and are auto-renewed before their 7-day expiry — they would otherwise be lost on a Claude Code CLI restart
- Provider status monitoring (Anthropic and OpenAI status pages) with in-app outage notifications

### Mobile-first, work from anywhere

- Fully responsive UI, designed for touch from the start
- Mobile-friendly terminal: touch selection, paste, proper scrollbar, scroll/select toggle, support for tmux and alternate-screen apps
- **Extra keys bar** (Essentials / More / F-keys) with modifiers (tap for one-shot, double-tap to lock), arrow keys, special characters, function keys
- User-defined key combos and reusable text snippets for the terminal
- Combined with a tunnel ([Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), [ngrok](https://ngrok.com/), [Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel), …), TwiCC turns a phone into a usable Claude or Codex frontend — see [Remote access](#remote-access) below

### Productivity tools

- **Command palette** (Ctrl+K / Cmd+K): jump to any project, session, or workspace, change session settings, and trigger common actions from a single keyboard-driven menu
- **Slash commands and file references**: `/` for Claude Code skills and commands, `$` for Codex skills, `@` for the file picker — all from the message input
- **Message snippets**: reusable text snippets with placeholders, scoped globally or per-project, for the prompts you keep retyping
- **Inline code comments**: click a line number in a code block to annotate, then send a formatted review comment back to the agent — human review of AI-generated code, right from the browser
- **Selection comments**: select text in Chat, Files, Git, or Terminal to copy it or attach a comment, then send the selection and your note back to the agent, preformatted and ready to go
- Full-text search across all sessions (Ctrl+Shift+F) and in-session search (Ctrl+F)
- Multiple simultaneous terminals, with optional custom `tmux.conf`
- Git integration: log, diffs (including side-by-side image diff), file browser, commit details
- Project and session archiving (including bulk archive of old sessions)

### Costs, usage and activity

- Per-session and per-project cost tracking
- Quota graphs and burn rate for the Claude Code and Codex 5h / 7-day windows
- Daily and weekly activity heatmaps and stats, per project, per workspace, and across all projects

### Workspaces and projects

- Group projects into named, color-coded **workspaces**, with optional auto-add by directory pattern
- Scoped session list, search, snippets, and aggregated stats per workspace
- Workspace-level Files, Git, and Terminal tabs in addition to per-project ones

### Self-aware: agent skills and CLI

TwiCC exposes a full `twicc` command-line interface — and a Claude Code / Codex plugin (auto-installed) whose skills wrap the same commands, so an agent can drive TwiCC from inside a running session. Either way you can inspect projects, workspaces, and sessions, run a full-text search, check usage and cost, and **create, reply to, update, and control sessions and their live processes** — every list/inspect command outputs JSON for scripting.

See [`SKILLS-AND-CLI.md`](SKILLS-AND-CLI.md) for the full reference, or run `twicc --help`.

### HTTP RPC API

The same CLI is also exposed over HTTP under `/rpc/`, so one TwiCC instance — or any HTTP client — can drive another over the network. Every command is auto-generated as a route from the CLI itself, so there is no separate API to keep in sync.

See [`RPC-API.md`](RPC-API.md) for authentication, the request/response shape, and the few HTTP-specific limitations (server-side absolute paths, base64 attachments, blocking waits).

### Orchestration

A session can spawn other sessions, which can spawn their own, forming a tree of cooperating agents. A leader/manager/worker skill family lets one agent split a task into sub-tasks across spawned sessions (optionally hidden from the UI), coordinate them through a shared scratch space, and aggregate the results — without a human in the loop for each step.

See [`ORCHESTRATION.md`](ORCHESTRATION.md).

## How it works

TwiCC reads the JSONL data files written by each provider and indexes them into a local SQLite database (`~/.twicc/db/data.sqlite`). Claude Code sessions are read from `~/.claude/projects/`; Codex sessions are read from `~/.codex/sessions/`. **Provider data files remain the source of truth** — TwiCC never modifies them. Whether you use Claude Code or Codex directly from the terminal or through TwiCC, everything shows up in the same place.

When you start a session or send messages through TwiCC, it uses the provider SDK under the hood: the [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk-python) for Claude Code and OpenAI's vendored Codex SDK for Codex. This means it uses your existing provider credentials and configuration — there is nothing extra to set up. The conversation data written by the provider is then picked up by TwiCC's file watcher and broadcast to the UI in real time over WebSocket.

On each startup, TwiCC detects changes and updates its database accordingly. While running, it watches the filesystem for new sessions and updates them in real time.

## Remote access

The interface is fully usable from a mobile browser. Combined with a tunnel service like [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), [ngrok](https://ngrok.com/), or [Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel), you can access TwiCC from anywhere and interact with Claude Code or Codex from your phone.

> **Important:** if you expose TwiCC over the internet, enable password protection (see [Configuration](#configuration)) and prefer a tunnel service with its own access control. TwiCC has no built-in access control beyond optional password protection.

> **Tip:** on Android, the author uses [Unexpected Keyboard](https://play.google.com/store/apps/details?id=juloo.keyboard2) for an even better terminal experience — it natively exposes Ctrl, Esc, Tab, and other keys that complement TwiCC's built-in keys bar.

## Requirements

- Claude Code and/or Codex already configured locally
- For existing history: a `~/.claude/projects/` directory created by Claude Code and/or a `~/.codex/sessions/` directory created by Codex

TwiCC needs Python 3.13+. If you install through `uvx` or `uv tool install` (recommended, see [Quick start](#quick-start)), `uv` will download and manage the right Python version for you — nothing to install by hand. If you go the `pip install` route, install Python 3.13 yourself first.

## Configuration

All configuration goes through environment variables, set in `~/.twicc/.env`:

| Variable              | Default     | Description                                |
|-----------------------|-------------|--------------------------------------------|
| `TWICC_PORT`          | `3500`      | Server port                                |
| `TWICC_PASSWORD_HASH` | *(empty)*   | Password hash to enable password protection (managed by `twicc password set`) |
| `TWICC_DATA_DIR`      | `~/.twicc/` | Data directory (database, logs, settings)  |

### Password protection

Set, clear, or check the password interactively. Use the same invocation prefix as for launching TwiCC — `twicc` if you installed it permanently, `uvx twicc` for a one-off run, or `uv run twicc` from a source checkout:

```bash
twicc password set      # prompt for a password (with confirmation) and write it to .env
twicc password clear    # disable password protection
twicc password status   # show whether password protection is enabled
```

Restart TwiCC after setting or clearing the password for the change to take effect.

## Platform support

TwiCC runs on **Linux** and **macOS**. There is no native Windows support — the codebase relies on Unix-specific APIs (PTY, process signals, process groups) that would require significant work to adapt, and the author does not have access to a Windows machine for development and testing.

**WSL (Windows Subsystem for Linux)** is the recommended path for Windows users. TwiCC has been reported to work correctly under WSL2. If you hit issues, please open an issue or a pull request.

## FAQ

### Can I use TwiCC while Claude Code or Codex is running?

Yes. TwiCC only reads provider data files and never modifies them.

### Where is my data stored?

By default in `~/.twicc/`. This includes the SQLite database, logs, and user settings. Set `TWICC_DATA_DIR` to change the location.

### Where are the logs?

In `~/.twicc/logs/backend.log` for the backend. This is the first file to check when troubleshooting.

### How do I reset the database?

Delete `~/.twicc/db/data.sqlite*` and restart TwiCC. It will rebuild from the provider source files.

### Is this allowed by Anthropic?

For Claude Code sessions, TwiCC uses the official [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk-python) with the Claude Code system prompt. This is permitted by Anthropic's terms of service.

**Billing change on June 15, 2026:** until that date, SDK usage is billed against the same plan quota as the regular Claude Code CLI. Starting **June 15, 2026**, Anthropic moves SDK usage to a **separate, plan-specific credits quota** dedicated to the SDK. In practice, TwiCC sessions will no longer share the Claude Code plan quota and may be more constrained depending on your plan tier — see Anthropic's documentation for details.

### Is this allowed by OpenAI?

For Codex sessions, TwiCC uses OpenAI's Codex SDK (vendored — see [`docs/codex-vendoring.md`](docs/codex-vendoring.md)) and the Codex CLI. OpenAI does not document any limitation on this kind of usage, and TwiCC sessions draw from the same plan quota as the regular Codex CLI.

### How can I support this project?

If you find TwiCC useful, consider [sponsoring me on GitHub](https://github.com/sponsors/twidi) — it means a lot and helps keep the project going.

## Development

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, `devctl.py` usage, building, and the release process. Conventions, architecture notes, and patterns live in [`AGENTS.md`](AGENTS.md) and [`CLAUDE.md`](CLAUDE.md). The Codex SDK vendoring is documented in [`docs/codex-vendoring.md`](docs/codex-vendoring.md).

## License

MIT
