Metadata-Version: 2.5
Name: luicode
Version: 1.0.1
Summary: The local gateway for agentic coding: one proxy and Admin UI across providers and coding agents
Project-URL: Homepage, https://github.com/Luigibarte4563/luicode
Project-URL: Repository, https://github.com/Luigibarte4563/luicode
Project-URL: Issues, https://github.com/Luigibarte4563/luicode/issues
License-File: LICENSE
Requires-Python: >=3.14.0
Requires-Dist: aiohttp>=3.14.3
Requires-Dist: anyio>=4.15.1
Requires-Dist: discord-py>=2.7.1
Requires-Dist: fastapi[standard]>=0.141.1
Requires-Dist: github-copilot-sdk==1.0.14
Requires-Dist: google-auth[requests]>=2.56.3
Requires-Dist: grpcio-tools>=1.81.1
Requires-Dist: grpcio>=1.84.0
Requires-Dist: httpx2[socks]<3,>=2.7.0
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: json5>=0.15.0
Requires-Dist: jsonschema>=4.25.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: markdown-it-py>=4.2.0
Requires-Dist: nvidia-riva-client>=2.26.0
Requires-Dist: openai>=3.18.0
Requires-Dist: pillow>=12.0.0; sys_platform == 'win32' or sys_platform == 'darwin'
Requires-Dist: pydantic>=2.13.5
Requires-Dist: pystray>=0.19.5; sys_platform == 'win32' or sys_platform == 'darwin'
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: python-telegram-bot>=22.8
Requires-Dist: requests[socks]>=2.34.2
Requires-Dist: simplejson>=4.1.2
Requires-Dist: tiktoken>=0.13.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.1
Requires-Dist: tomlkit>=0.13.3
Requires-Dist: uvicorn>=0.53.0
Provides-Extra: browser
Requires-Dist: browser-harness>=0.1.13; extra == 'browser'
Requires-Dist: cdp-use>=1.4.5; extra == 'browser'
Provides-Extra: voice-local
Requires-Dist: accelerate>=1.15.0; extra == 'voice-local'
Requires-Dist: librosa>=1.0.0; extra == 'voice-local'
Requires-Dist: torch>=2.14.0; extra == 'voice-local'
Requires-Dist: transformers>=5.17.0; extra == 'voice-local'
Description-Content-Type: text/markdown

<div align="center">

<h1>
  <picture>
    <source media="(prefers-color-scheme: light)" srcset="assets/luicode-wordmark-light.svg">
    <img src="assets/luicode-wordmark-dark.svg" alt="luicode" width="560">
  </picture>
</h1>

<p>
  <em>The local gateway for agentic coding.</em>
</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Python 3.14](https://img.shields.io/badge/python-3.14-3776ab.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![Package Manager: uv](assets/package-manager-uv.svg)](https://github.com/astral-sh/uv)
[![Testing: Pytest](https://img.shields.io/badge/Testing-Pytest-ad1457.svg?style=for-the-badge)](https://github.com/Luigibarte4563/luicode/actions/workflows/tests.yml)
[![Type Checker: Ty](https://img.shields.io/badge/Type%20Checker-ty-fdd835.svg?style=for-the-badge)](https://pypi.org/project/ty/)
[![Formatter: Ruff](https://img.shields.io/badge/Formatter-ruff-bf4b00.svg?style=for-the-badge)](https://github.com/astral-sh/ruff)
[![Logging: Loguru](https://img.shields.io/badge/logging-loguru-00695c.svg?style=for-the-badge)](https://github.com/Delgan/loguru)
[![Browser automation: optional](https://img.shields.io/badge/browser%20automation-optional-8b5cf6.svg?style=for-the-badge)](https://github.com/browser-use/browser-harness)

[Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-your-client) · [Integrations](#optional-integrations) · [Browser automation](#browser-automation) · [Manage](#manage-your-installation)

</div>

<p align="center">
  <em>Independent open-source project. Not affiliated with or endorsed by Anthropic. Claude and Claude Code are trademarks of Anthropic.</em>
</p>

luicode is a local gateway that runs your favorite coding agents against a unified
catalog of provider models — free tiers, subscriptions, and local servers — from
one configurable proxy with a browser-admin UI.

## What You Get

- **55 ToS-friendly providers. 1.3B+ free tokens every month.** Use free, paid, subscription, and local models from one searchable UI without putting your account at risk. luicode follows provider terms and removes integrations if they stop being allowed.
- **10 coding agents. One model catalog.** Run [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://github.com/openai/codex), [Pi](https://github.com/earendil-works/pi), [OpenCode](https://github.com/anomalyco/opencode), [Cline](https://github.com/cline/cline), [Hermes](https://github.com/NousResearch/hermes-agent), [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [Grok Build](https://github.com/xai-org/grok-build), [Muse Code](https://research.meta.ai/blog/introducing-muse-code-and-muse-spark-1-2/), or [Aider](https://aider.chat/) with your luicode models.
- **Keep coding through provider outages.** After retries are exhausted, luicode automatically tries your next configured model without making you restart the turn—across every client.
- **Up to 90% fewer terminal-output tokens.** Optional [RTK](https://github.com/rtk-ai/rtk) filters common command output, while five luicode optimizations handle quota probes, command-prefix detection, titles, suggestions, and filepaths without calling a provider.
- **Native Code sessions in your browser.** Choose a folder and run Codex in the browser with real-time and background support. Freely switch providers/models in the same session. Support for switching harnesses in the same session coming soon!
- **Terminal, desktop, IDE, or phone.** Work through native launchers, [VS Code](https://code.visualstudio.com/), [Codex App](https://learn.chatgpt.com/docs/app), [JetBrains](https://www.jetbrains.com/), [Discord](https://discord.com/), or [Telegram](https://telegram.org/).
- **Voice notes in. Code out.** Talk to your agent using local [Whisper](https://github.com/openai/whisper) or [NVIDIA NIM](https://docs.nvidia.com/nim/speech/latest/asr/deploy-asr-models/whisper.html) transcription.
- **Agent capabilities stay intact.** Stream responses, use tools, preserve native interleaved thinking for maximum performance, send images, and route [Fable](https://www.anthropic.com/claude/fable), [Opus](https://www.anthropic.com/claude/opus), [Sonnet](https://www.anthropic.com/claude/sonnet), and [Haiku](https://www.anthropic.com/claude/haiku) independently with compatible models.
- **Browser automation (optional).** Enable the `browser` extra to give coding agents the ability to navigate, click, fill forms, and extract data from web pages using Chrome DevTools Protocol — powered by the same engine as [JEV-Ultrafast](https://github.com/browser-use/jev-ultrafast).

Free-tier availability and limits are controlled by each provider and may change.

## How It Works

<div align="center">
  <img src="assets/luicode-architecture.svg" alt="Architecture: a single local gateway fanning out to many providers for many coding agents" width="700">
</div>

luicode runs one local gateway process (`luicode-server`). Coding agents connect
to it through `luicode-*` launchers or IDE/app integrations, and it routes every
request in the catalog to the provider and model you picked — with fallbacks,
reasoning control, and token-saving optimizations applied in between.

## Quick Start

<a id="install"></a>

### 1. Install

#### macOS / Linux

```bash
curl -fsSL "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.sh" | sh
```

#### Windows PowerShell

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.ps1")))
```

#### Android (Termux)

Install [Termux](https://f-droid.org/packages/com.termux/) from F-Droid first,
then run this single command:

```bash
curl -fsSL "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.sh" | sh
```

That is the whole install. The installer detects Termux automatically and:

- updates the Termux package lists and installs only the packages you are
  missing (`python`, `git`, `curl`)
- checks that Python is new enough for LUICode (3.14 or newer)
- keeps the source checkout in `~/.luicode-src` — never in `~/.luicode`, which
  holds your configuration and data
- installs LUICode into that checkout with `pip install -e .`
- adds the directory holding `luicode` and `luicode-server` to your `PATH`
  from `~/.bashrc` or `~/.zshrc`, inside a single managed `# >>> LUICode PATH >>>`
  block so reruns never duplicate it
- verifies that both commands run, and prints the web interface URL

Open a **new** Termux session afterwards. Then:

```bash
luicode-server
```

See [docs/android.md](docs/android.md) for persistence, wake locks, LAN access,
and how to update or uninstall.

Note: coding agents (Claude Code, Codex, OpenCode, …) are installed separately
with the Linux installer described above; the Termux one-command install covers
the gateway itself. `termux-wake-lock` is never run for you — the installer only
prints it as an optional tip.

See [docs/android.md](docs/android.md) for complete Android/Termux setup including persistence, wake locks, and LAN access.

When prompted, choose at least one coding agent and optionally RTK. You can review the installers before running them: [install.sh](scripts/install.sh) and [install.ps1](scripts/install.ps1).

**Optional:** Enable browser automation for web interaction capabilities (not available on Android):

```bash
uv sync --extra browser
```

This installs `browser-harness` and `cdp-use` for Chrome DevTools Protocol automation.

### 2. Start luicode

#### Windows

Open **luicode** from your desktop or Start menu.

#### macOS

Open **luicode** from your desktop or Applications folder.

#### Linux

Run:

```bash
luicode-server
```

#### Android (Termux)

Open a **new** Termux session, then run:

```bash
luicode-server
```

`luicode` is an alias for the same server, so either works.

For background persistence, acquire a wake lock and disable battery optimization:

```bash
termux-wake-lock
luicode-server
```

The server listens on port **8082** by default, so the Admin UI is at
<http://127.0.0.1:8082/admin>. Change it with `PORT` in `~/.luicode/.env`.

See [docs/android.md](docs/android.md) for auto-start (Termux:Boot), notifications (Termux:API), and LAN access.

luicode opens the Admin UI after starting. On Windows and macOS, use the tray or
menu-bar icon to open Admin, restart, or quit. On Android, use `termux-open-url` to open the Admin UI. When using `luicode-server`, keep its terminal open.

<a id="nvidia-nim-provider"></a>

### 3. Configure NVIDIA NIM

1. Create an API key at [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys).
2. Open the Admin UI URL from the server log.
3. Paste the key into `NVIDIA_NIM_API_KEY`.
4. Leave `MODEL` on the default `nvidia_nim/nvidia/nemotron-3-super-120b-a12b`, or search the model dropdown and select another model.
5. Click **Apply**.

To protect the local proxy with a bearer token, enable **Proxy Authentication**
in Admin.

### 4. Run Your Coding Agent

Claude Code:

```bash
luicode-claude
```

Codex:

```bash
luicode-codex
```

Pi:

```bash
luicode-pi
```

OpenCode 2:

```bash
luicode-opencode
```

To upgrade from OpenCode 1, rerun the luicode installer with OpenCode selected. It
upgrades the native installation in `~/.opencode/bin`; for npm or other package
managers, follow [OpenCode's migration instructions](https://opencode.ai/v2/docs/migrate-v1/)
first. For npm v1, run `npm uninstall -g opencode-ai`, then rerun the luicode installer.
Close OpenCode before upgrading. OpenCode manages its own data upgrades.

RTK integration is temporarily unavailable for OpenCode 2. RTK continues to work
with the other supported agents.

Use `luicode-opencode` for coding and sessions. Use plain `opencode` for commands
such as upgrades, service management, ACP, and MCP setup.

Cline:

```bash
luicode-cline
```

Hermes:

```bash
luicode-hermes
```

DeepSeek Harness Web:

```bash
luicode-dsh
```

Grok Build:

```bash
luicode-grok
```

Muse Code:

```bash
luicode-muse
```

Aider:

```bash
luicode-aider
```

## Choose A Provider

1. Open a provider link below for its key, models, or setup instructions.
2. In the Admin UI, configure the listed setting. For OpenAI / ChatGPT
   subscription access, use **Providers → OAuth providers** instead.
3. Search the `MODEL` dropdown and select a model. If the provider cannot list
   models, enter `<provider-id>/<exact-provider-model-id>` manually.
4. Click **Apply**.

Optional: add an ordered **Fallback Models** list under **Model config**. It
applies to every connected client. A failed request may reach and consume usage
from more than one provider before succeeding.

<details>
<summary><strong>Provider catalog</strong></summary>

| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
| [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [ClinePass](https://docs.cline.bot/getting-started/clinepass) | `CLINE_API_KEY` | `cline_pass/cline-pass/kimi-k3` |
| [OpenAI / ChatGPT](https://learn.chatgpt.com/docs/auth) | Connect ChatGPT in the Admin UI | `openai/<model-id>` |
| [OpenAI API](https://platform.openai.com/api-keys) | `OPENAI_API_KEY` | `openai_api/gpt-5.6-sol` |
| [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-sdk/auth/authenticate) | Connect GitHub Copilot in the Admin UI | `github_copilot/<model-id>` |
| [xAI (Grok)](https://console.x.ai/team/default/api-keys) | `XAI_API_KEY` | `xai/grok-4.5` |
| [QwenCloud Token Plan](https://home.qwencloud.com/api-keys) | `QWENCLOUD_API_KEY` | `qwencloud/qwen3.7-plus` |
| [QwenCloud Coding Plan](https://home.qwencloud.com/api-keys) | `QWENCLOUD_CODING_API_KEY` | `qwencloud_coding/qwen3.7-plus` |
| [Together AI](https://api.together.ai/settings/api-keys) | `TOGETHER_API_KEY` | `together/zai-org/GLM-5.2` |
| [DeepInfra](https://deepinfra.com/dash/api_keys) | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V4-Flash` |
| [SiliconFlow](https://cloud.siliconflow.com/account/ak) | `SILICONFLOW_API_KEY` | `siliconflow/Qwen/Qwen3-32B` |
| [Nebius Token Factory](https://tokenfactory.nebius.com/project/api-keys) | `NEBIUS_API_KEY` | `nebius/Qwen/Qwen3-30B-A3B` |
| [Chutes](https://chutes.ai/docs/getting-started/authentication) | `CHUTES_API_KEY` | `chutes/Qwen/Qwen3-32B-TEE` |
| [Featherless AI](https://featherless.ai/account/api-keys) | `FEATHERLESS_API_KEY` | `featherless/Qwen/Qwen3-32B` |
| [Agnes AI](https://agnes-ai.com/) | `AGNES_API_KEY` | `agnes/agnes-2.0-flash` |
| [ZenMux](https://zenmux.ai/platform/pay-as-you-go) | `ZENMUX_API_KEY` | `zenmux/deepseek/deepseek-v4-flash-free` |
| [W&B Inference](https://wandb.ai/settings) | `WANDB_API_KEY` | `wandb/openai/gpt-oss-20b` |
| [Azure OpenAI](https://learn.microsoft.com/azure/foundry/openai/how-to/chatgpt) | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_BASE_URL` | `azure_openai/<deployment-name>` |
| [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
| [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |
| [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
| [Mistral La Plateforme](https://console.mistral.ai/) | `MISTRAL_API_KEY` | `mistral/devstral-small-latest` |
| [Mistral Codestral](https://console.mistral.ai/) | `CODESTRAL_API_KEY` | `mistral_codestral/codestral-latest` |
| [OpenCode Zen](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode_zen/gpt-5.3-codex` |
| [OpenCode Go](https://opencode.ai/auth) | `OPENCODE_API_KEY` | `opencode_go/minimax-m2.7` |
| [Vercel AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers) | `AI_GATEWAY_API_KEY` | `vercel/openai/gpt-5.5` |
| [Amazon Bedrock](https://console.aws.amazon.com/bedrock/) | `AWS_BEARER_TOKEN_BEDROCK` | `bedrock/openai.gpt-oss-120b` |
| [Hugging Face Inference Providers](https://huggingface.co/settings/tokens) | `HUGGINGFACE_API_KEY` | `huggingface/Qwen/Qwen3-Coder-480B-A35B-Instruct:fastest` |
| [Cohere](https://dashboard.cohere.com/api-keys) | `COHERE_API_KEY` | `cohere/command-a-plus-05-2026` |
| [Wafer](https://wafer.ai/) | `WAFER_API_KEY` | `wafer/DeepSeek-V4-Pro` |
| [Kimi API](https://platform.moonshot.ai/console/api-keys) | `KIMI_API_KEY` | `kimi/kimi-k2.5` |
| [Kimi Code](https://www.kimi.com/code/console) | `KIMI_CODE_API_KEY` | `kimi_code/k3` |
| [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` |
| [Cerebras Inference](https://cloud.cerebras.ai/) | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b` |
| [SambaNova](https://cloud.sambanova.ai/apis) | `SAMBANOVA_API_KEY` | `sambanova/Meta-Llama-3.3-70B-Instruct` |
| [Kilo.ai](https://kilo.ai) | `KILO_API_KEY` | `kilo/kilo-auto/free` |
| [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` |
| [Novita AI](https://novita.ai/settings/key-management) | `NOVITA_API_KEY` | `novita/deepseek/deepseek-v4-flash-0731` |
| [Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/) | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` | `cloudflare/@cf/moonshotai/kimi-k2.6` |
| [Z.ai Coding Plan](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai/glm-5.2` |
| [Z.ai API (pay as you go)](https://z.ai/manage-apikey/apikey-list) | `ZAI_API_KEY` | `zai_api/glm-4.7-flash` |
| [TokenRouter](https://www.tokenrouter.com/) | `TOKENROUTER_API_KEY` | `tokenrouter/moonshotai/kimi-k3-free` |
| [NaraRoute](https://router.bynara.id/) | `NARAROUTE_API_KEY` | `nararoute/kimi-k3-free` |
| [Poolside AI](https://platform.poolside.ai/) | `POOLSIDE_API_KEY` | `poolside/poolside/laguna-s-2.1` |
| [LLM7.io](https://dash.llm7.io/) | `LLM7_API_KEY` | `llm7/default` |
| [Scaleway](https://console.scaleway.com/iam/api-keys) | `SCW_SECRET_KEY` | `scaleway/deepseek/deepseek-v4-flash` |
| [Lightning AI](https://lightning.ai/) | `LIGHTNING_API_KEY` | `lightning/lightning-ai/Qwen3.8-27B` |
| [Experiential Labs](https://platform.experientiallabs.ai/) | `EXPLABS_API_KEY` | `experiential/union-alpha` |
| [Cheaper Inference](https://cheaperinference.com/signup) | `CHEAPER_INFERENCE_API_KEY` | `cheaperinference/gpt-5.4-mini` |
| [Ollama Cloud](https://ollama.com/settings/keys) | `OLLAMA_API_KEY` | `ollama_cloud/qwen3-coder:480b` |
| [LM Studio](https://lmstudio.ai/) | `LM_STUDIO_BASE_URL` | `lmstudio/<model-id>` |
| [llama.cpp](https://github.com/ggml-org/llama.cpp) | `LLAMACPP_BASE_URL` | `llamacpp/<model-id>` |
| [Ollama](https://ollama.com/) | `OLLAMA_BASE_URL` | `ollama/<model-tag>` |

</details>

<details>
<summary><strong>Provider-specific setup</strong></summary>

- OpenAI / ChatGPT uses your ChatGPT subscription rather than an API key. Connect from
  **Providers → OAuth providers → OpenAI / ChatGPT → Connect** in the Admin UI
  and finish signing in through your browser. Restart an already-running agent after connecting.
- OpenAI API uses a separate Platform API key. Enter it under
  **Providers → Cloud providers → OpenAI API → Configure**. The model list may
  include IDs that cannot handle coding requests. Choose a text-generation model.
- GitHub Copilot uses your signed-in GitHub account and subscription. Install
  [Copilot CLI 1.0.83](https://github.com/github/copilot-cli/releases/tag/v1.0.83)
  on PATH, then choose **Providers → OAuth providers → GitHub Copilot → Connect**.
  luicode reuses the native profile or shows a GitHub device code when sign-in is needed.
  You can also sign in first with `copilot login --device-code`. Select a concrete
  `github_copilot/<model-id>` from the discovered list; available models and quotas
  depend on your subscription and organization policies. Restart an already-running
  agent after connecting. Disconnect stops luicode use and leaves the native login intact.
  luicode pins its SDK and CLI compatibility because direct endpoint access is experimental.
- Azure OpenAI uses the deployment names from your resource. Set
  `AZURE_OPENAI_BASE_URL` to its complete v1 endpoint, such as
  `https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`, and select a
  deployment that supports Chat Completions. Enter the deployment name as a
  custom model slug if it does not appear in the model dropdown.
- Mistral Codestral uses a separate key from Mistral La Plateforme.
- Kimi Code subscription keys use `kimi_code/`. Kimi API credit keys use
  `kimi/`. Kimi Code plans are for personal interactive coding-agent use under
  [Kimi's community guidelines](https://www.kimi.com/code/docs/en/kimi-code/community-guidelines.html).
- QwenCloud Coding Plan keys use `qwencloud_coding/`. QwenCloud Token Plan keys
  use `qwencloud/`. The keys and endpoints are not interchangeable. Coding Plan
  is for local, personal, interactive coding-agent use under the
  [Coding Plan terms](https://www.alibabacloud.com/help/en/model-studio/coding-plan).
- OpenCode Zen and OpenCode Go share `OPENCODE_API_KEY` but use the explicit
  `opencode_zen/` and `opencode_go/` model prefixes.
- For Amazon Bedrock, set `BEDROCK_BASE_URL` to the URL for the same region as
  the API key and select one of the listed models.
- Vertex AI uses Google Application Default Credentials instead of an API key.
  Locally, run `gcloud auth application-default login` once. Service-account
  files and attached service accounts also work. Set `VERTEX_PROJECT_ID`, and
  optionally change `VERTEX_LOCATION` from its `global` default.
- Cloudflare requires both its API token and account ID.
- For Ollama Cloud, use the exact model IDs shown in the model picker. Local
  Ollama uses the separate `ollama/` prefix.
- Prefer tool-capable models for coding agents. Local models also need enough context for the agent's system prompt and tool definitions.

</details>

<details>
<summary><strong>Local provider setup</strong></summary>

### LM Studio

Start LM Studio's local server, load a tool-capable model, and use the model identifier shown by LM Studio with the `lmstudio/` prefix. The default URL is `http://localhost:1234/v1`.

### llama.cpp

Start `llama-server` with its OpenAI-compatible Chat Completions API and enough context for the model. Use the local model ID with the `llamacpp/` prefix. `LLAMACPP_BASE_URL` defaults to `http://localhost:8080/v1`; luicode accepts either the server root or an explicit `/v1` suffix.

### Ollama

```bash
ollama pull llama3.1
ollama serve
```

Use the tag shown by `ollama list` with the `ollama/` prefix. `OLLAMA_BASE_URL` defaults to `http://localhost:11434`; luicode accepts either the root URL or an explicit `/v1` suffix.

</details>

<details>
<summary><strong>Optional model-tier routing</strong></summary>

`MODEL` is the fallback for every request. Select a model for `MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, or `MODEL_HAIKU` to override an individual Claude Code tier. Select **None** to use `MODEL`.

</details>

<details>
<summary><strong>Reasoning control</strong></summary>

Open **Admin UI → Model config → Reasoning** and select the behavior you want.

| Selection | Behavior |
| --- | --- |
| **From client** (default) | Use the effort sent by your coding agent. If none is sent, keep the provider default. |
| **Off** | Request reasoning to be disabled. |
| **Low**, **Medium**, **High**, **X-High**, or **Max** | Override the client with the selected reasoning level. |
| **Inherit** (Fable, Opus, Sonnet, and Haiku only) | Use the root Reasoning selection. |

Providers that do not support a selected control retain their own behavior.

</details>

<a id="connect-your-client"></a>

## Connect Your Client

For terminal use, start `luicode-server`, then run `luicode-claude`, `luicode-codex`,
`luicode-pi`, `luicode-opencode`, `luicode-cline`, `luicode-hermes`, `luicode-dsh`, `luicode-grok`,
`luicode-muse`, or `luicode-aider`.

For editor and app integrations, install the client, start luicode, then open
**Admin UI → Integrations** and click **Connect** on its card.

- **Claude Code in VS Code** — install the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code).
- **Claude Desktop** — install [Claude Desktop](https://claude.ai/download). Fully quit it before connecting or disconnecting, then reopen it. Disconnect returns to normal Claude sign-in.
- **Codex in VS Code and App** — install the [Codex extension](https://marketplace.visualstudio.com/items?itemName=openai.chatgpt) or Codex App.
- **Claude Code in JetBrains ACP** — install Claude Agent in JetBrains AI Assistant and start it once, then click **Connect** in luicode. Reopen the IDE, select **Claude Code (LUICODE)**, and start a new chat. After JetBrains updates the agent, restart luicode before starting a new chat. Requires a local IDE in its standard installation locations.

Reload VS Code or restart the app/IDE after connecting. In Codex and Claude Desktop, select a luicode
model from the model picker. luicode keeps connected integrations up to date when it
starts; reload or restart the client when luicode reports updated settings. Use
**Disconnect** on the same card to remove the integration.

Run luicode on the same computer and in the same user environment as the client you
are configuring.

<a id="optional-integrations"></a>

## Optional Integrations

Configure integrations from **Admin UI → Messaging**, then click **Apply**.

<details>
<summary><strong>Discord bot</strong></summary>

1. Create a bot in the [Discord Developer Portal](https://discord.com/developers/applications).
2. Enable **Message Content Intent** and invite it with read, send,
   message-history, and **Manage Messages** permissions so `/clear` can remove
   user prompts.
3. Set **Messaging Platform** to **discord**.
4. Enter **Discord Bot Token**, **Allowed Discord Channels**, and an absolute **Allowed Directory**.
5. Apply the settings and restart the server if requested.

</details>

<details>
<summary><strong>Telegram bot</strong></summary>

1. Create a bot with [@BotFather](https://t.me/BotFather).
2. Get your numeric user ID from [@userinfobot](https://t.me/userinfobot).
   In groups, grant the bot permission to delete messages.
3. Set **Messaging Platform** to **telegram**.
4. Enter **Telegram Bot Token**, **Allowed Telegram User ID**, and an absolute **Allowed Directory**.
5. Apply the settings and restart the server if requested.

</details>

### Messaging commands

| Usage | Behavior |
| --- | --- |
| `/stats` | Show session state. |
| Standalone `/stop` | Cancel all work. |
| Reply with `/stop` | Cancel only the selected request while other queued requests continue. |
| Standalone `/clear` | Reset all luicode state and remove every tracked message in that chat, including user prompts, voice notes, luicode replies, Telegram's online notice, and the clear command itself. |
| Reply with `/clear` | Delete the selected message and its literal platform reply subtree while preserving its ancestors and siblings. |

<details>
<summary><strong>Voice notes</strong></summary>

NVIDIA NIM transcription support is included in every installation. In **Admin UI → Messaging → Voice**, enable voice notes, select `nvidia_nim`, and choose a supported model. Configure your **NVIDIA NIM API key** on the Providers page.

For local Whisper on CPU or CUDA, re-run the installer with the local voice option (not available on Android):

macOS/Linux:

Local Whisper on CPU or CUDA:

```bash
curl -fsSL "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.sh" | sh -s -- --voice-local
```

Local Whisper with CUDA 13.0:

```bash
curl -fsSL "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.sh" | sh -s -- --voice-local --torch-backend cu130
```

Windows PowerShell:

Local Whisper on CPU or CUDA:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.ps1"))) -VoiceLocal
```

Local Whisper with CUDA 13.0:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install.ps1"))) -VoiceLocal -TorchBackend cu130
```

Restart `luicode-server`. In **Admin UI → Messaging → Voice**, enable voice notes, select `cpu`, `cuda`, or `nvidia_nim`, and choose the Whisper model. Local gated models need `HUGGINGFACE_API_KEY`; NVIDIA NIM transcription needs `NVIDIA_NIM_API_KEY`.

**Android/Termux:** Local Whisper is not supported. Use NVIDIA NIM remote transcription only.

</details>

<details>
<summary><strong>Browser automation</strong></summary>

Enable browser automation for coding agents to interact with web pages programmatically. This feature uses Chrome DevTools Protocol (CDP) via [browser-harness](https://github.com/browser-use/browser-harness) — the same engine that powers [JEV-Ultrafast](https://github.com/browser-use/jev-ultrafast).

**Not available on Android/Termux** (no embeddable Chromium).

### Install

```bash
# With the browser extra
uv sync --extra browser
```

Or when using the installer, select the browser automation option (if available on your platform).

### Requirements

- Chrome or Chromium with remote debugging enabled (managed automatically by browser-harness)
- The browser-harness daemon will start on first use

### Capabilities

When enabled, coding agents connected through luicode can:
- **Navigate** to URLs and wait for page load
- **Observe** page state — get interactive elements (buttons, inputs, dropdowns, links) with labels and metadata
- **Click** elements by their observed index
- **Fill** text into input fields, textareas, and comboboxes
- **Select** options from dropdown menus
- **Scroll** the page up or down
- **Wait** for page to settle after interactions
- **Run multi-step tasks** as a sequence of actions

### For Developers

The browser automation is exposed via the `BrowserToolsPort` protocol in the application layer:

```python
from luicode.application.browser_tools.ports import BrowserToolsPort


# In your handler/service
async def my_handler(browser_tools: BrowserToolsPort):
    await browser_tools.navigate("https://example.com")
    state = await browser_tools.observe()
    # state.elements contains indexed interactive elements
    await browser_tools.click(node_id=5)  # Click the 5th element
    await browser_tools.fill(node_id=3, text="search query")
    await browser_tools.wait()
```

The runtime implementation (`BrowserToolsClient` in `luicode.runtime.browser_tools`) handles:
- CDP session management via browser-harness
- Atomic DOM snapshots with element indexing
- Staleness detection (page fingerprint guards)
- Post-input observation (autocomplete suggestions, animations)
- Screenshot capture (optional)

### Notes

- This is an **optional** feature — luicode works fully without it
- No API keys required (uses local Chrome instance)
- TypeSafe integration for structured decision-making is not included in this MVP
- The browser runs in a background tab with focus emulation to prevent throttling

</details>

## Manage Your Installation

Run `luicode-server --version` to check the installed version without starting luicode.

### Update

Stop all running luicode commands, then run:

```sh
luicode-update
```

For local voice support, include `--voice-local` (macOS/Linux) or `-VoiceLocal` (Windows), plus your `--torch-backend` or `-TorchBackend` option if used.

If your installation does not have `luicode-update` yet, run the [installer](#install) once to add it.

### Muse Code on native Windows

Rerunning luicode's Windows installer with Muse Code selected installs or updates luicode's managed Muse executable. To install or update only Muse Code:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/install-muse.ps1")))
```

To remove the Muse Code copy installed by LUICODE, keeping its data:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/uninstall-muse.ps1")))
```

luicode's ordinary uninstaller below continues to leave Muse Code installed.

### Uninstall

Stop every running luicode command before uninstalling.

**Removes**

- luicode, including its desktop launcher and commands
- `~/.luicode/`

**Keeps**

- uv and Python
- Your coding agents and RTK

macOS/Linux:

```bash
curl -fsSL "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/uninstall.sh" | sh
```

Windows PowerShell:

```powershell
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/Luigibarte4563/luicode/main/scripts/uninstall.ps1")))
```

## Project Links

- [Report bugs or request features](https://github.com/Luigibarte4563/luicode/issues)
- [Contributing guide](CONTRIBUTING.md)
- [Product E2E smoke tests](smoke/README.md)
- [Android/Termux guide](docs/android.md)

## License

MIT License. See [LICENSE](LICENSE) for details. luicode is an independent
continuation of the Free Claude Code project; the original author retains the
copyright as recorded in the MIT license notice.
