claude-code-mini

A Claude Code–style coding assistant for your terminal, or your browser, that runs on an Anthropic API key through the Claude Agent SDK. It is a single Python file that runs on macOS, Linux and Windows 11, installs without sudo or admin rights, and its interface is in Bahasa Indonesia.

Unofficial community project, not affiliated with or endorsed by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

A real session with Claude Sonnet. Asked (in Indonesian) to run the tests and fix whatever fails, Claude asks before running the test command, sees test_bagi fail, finds that bagi ("divide") multiplies, fixes it, and runs the tests again. Every part of the screen is explained in Your first session.

Contents

• Features
• Install in one command (macOS, Linux, Windows 11)
• Step-by-step setup, by hand: 1 requirements · 2 Python and Git · 3 API key · 4 install · 5 PATH · 6 save the key · 7 check
• Your first session, with screenshots
• The browser GUI, with screenshots
• Everyday use
• What the Indonesian labels mean
• Update and uninstall
• Troubleshooting
• Full tutorial · How it works · Tests · Notes · License

Features

• Claude Code look and feel: see which files Claude reads, line-numbered diffs of its edits, the commands it runs, its todo list and its sub-agents, plus live token, cost and context usage.
• Claude Code permission prompts: 1 yes · 2 yes, and don't ask again (saved to .claude/settings.local.json) · 3 no, and tell Claude what to do instead.
• Permission modes: default, acceptEdits and plan (cycle with Shift+Tab), a plan approval panel, and --yolo for sandboxes.
• Terminal or browser: the same assistant runs in the terminal or, with --gui, as a local web app in your browser (chat bubbles, tool cards with diffs, permission buttons), with no extra dependencies.
• Type while Claude works: the prompt never locks. A message you send mid-turn is read by Claude as soon as the tool call that is running finishes (steering, like Claude Code); commands queue until the turn ends.
• Background agents and commands you can watch: live progress under the prompt, /tasks and /stop, and Claude automatically follows up when they finish.
• /goal: Claude keeps working until a condition you define is met (built on Claude Code's own /goal).
• Session control: /rewind file changes, continue old conversations with /resume or -c, automatic reconnect after a crash.
• Copy answers and commands: every code block in Claude's answers gets a number (📋 /copy 2 in the terminal, a copy button in the GUI). /copy copies the last answer and /copy 2 that code block, also over SSH.
• A GUI that feels like a chat app: answers stream in as Claude writes them; a history sidebar lists the conversations in the project folder, with search, rename and delete; attach files and images with 📎, drag and drop, or paste; a soft chime and a browser notification when Claude finishes or needs your permission while you are in another tab.
• Input shortcuts: !command runs a shell command and hands the output to Claude, @path attaches files or folders, # note saves a note to CLAUDE.md.
• Scriptable: -p one-shot mode with meaningful exit codes for scripts and CI.
• Billing safety: it refuses to run unless it is authenticated with ANTHROPIC_API_KEY, so it never draws on a Claude Pro/Max subscription. An optional --budget caps what a session can spend.
• One-command install on macOS, Linux and Windows 11: the installer sets up Python if needed, asks for your API key, checks it with Anthropic, and saves it. claude-code-mini --update fetches the newest version later, and the app tells you when one is out.

Install in one command

The installer does everything for you and asks for your API key at the end, so the only thing to prepare is the key itself (how to create one).

On macOS and Linux, in a terminal:

curl -fsSL https://raw.githubusercontent.com/imransetiadi/claude-code-mini/main/install.sh | bash

On Windows 11, in PowerShell: press the Windows key, type PowerShell (or Terminal), press Enter, then run:

irm https://raw.githubusercontent.com/imransetiadi/claude-code-mini/main/install.ps1 | iex

Windows: PowerShell only. irm and iex are PowerShell commands, so in a bash terminal on Windows (the local terminal of MobaXterm, Git Bash, Cygwin) this line fails with irm: command not found. Afterwards, run claude-code-mini in Windows Terminal (PowerShell, or Git Bash inside Windows Terminal), not in MobaXterm's local terminal or the separate Git Bash window: those are not Windows consoles. In WSL, use the macOS/Linux line instead: it installs the Linux version inside WSL.

When it asks Tempel API key ("paste the API key"), paste your key and press Enter. Nothing appears while you paste, so the key never shows on screen. Then go to a project folder and start it:

• macOS and Linux: open a new terminal first (or run the source … command the installer prints), then run claude-code-mini.
• Windows: in the same window, run claude-code-mini.

Use claude-code-mini --gui for the browser version. Your first session is explained step by step in Your first session.

What the installer does:

1. Finds Python 3.10 or newer. If there is none, it asks, then installs one: with Homebrew on macOS, apt-get on Ubuntu/Debian (with sudo), winget on Windows, or uv into your home folder without sudo when none of those is available. On Windows it also offers Git for Windows, because Claude Code runs its commands through Git Bash.
2. Downloads claude-code-mini.py and runs --setup, which creates the private virtualenv and the claude-code-mini command (step 4 explains what that does). A download that is cut short never replaces a working installation.
3. Puts ~/.local/bin on your PATH. On macOS and Linux it adds a small block, marked # >>> claude-code-mini >>>, to the end of ~/.zshrc, ~/.bashrc or ~/.bash_profile. On Windows it adds the folder to your user PATH.
4. Asks for your API key and checks it with a free request to Anthropic. A key that Anthropic rejects is asked for again, up to three times, and an empty answer skips this step. The key is saved in ~/.config/claude-code-mini/api_key, readable only by your account and loaded by that same block; on Windows, as the user environment variable ANTHROPIC_API_KEY.

To update to the latest version, run the same command again: a saved key is not asked for again. To replace the key, run it with CCMINI_NEW_KEY=1: curl -fsSL … | CCMINI_NEW_KEY=1 bash, or on Windows $env:CCMINI_NEW_KEY = "1" first. Without a terminal (CI, Docker) the installer asks nothing, installs what it needs, and skips the API key.

Installer line	Meaning
Pasang Python 3.13 lewat …? [Y/n]	Install Python 3.13 with …? Enter means yes.
Mengunduh claude-code-mini.py (main) …	Downloading claude-code-mini.py from the main branch.
Tempel API key (tidak tampil di layar; Enter kosong = lewati)	Paste the API key (not shown on screen; an empty Enter skips it).
Key diterima Anthropic / Key ditolak Anthropic (401)	Anthropic accepted / rejected the key.
Itu bukan API key Anthropic (harus diawali sk-ant-)	That isn't an Anthropic API key (it must start with sk-ant-).
claude-code-mini siap dipakai	claude-code-mini is ready to use.

Prefer to read a script before running it? Download it first, read it, then run it:

curl -fsSLO https://raw.githubusercontent.com/imransetiadi/claude-code-mini/main/install.sh

bash install.sh

On Windows: irm https://raw.githubusercontent.com/imransetiadi/claude-code-mini/main/install.ps1 -OutFile install.ps1, then powershell -ExecutionPolicy Bypass -File install.ps1.

Step-by-step setup

Prefer to install by hand, or want to know exactly what the installer does? The whole setup takes about ten minutes on a fresh computer. Each step has instructions for macOS, Ubuntu/Debian and Windows 11: follow only the ones for your system.

Step 1: Check the requirements

You need	Notes
macOS, Linux or Windows 11	Daily use on macOS and Ubuntu 26.04; automated tests on Windows, Ubuntu and macOS (Tests).
Python 3.10 or newer	Installed in step 2. claude-code-mini puts its own libraries in a private virtualenv.
git	Installed in step 2. Used to download the code and to update it.
An Anthropic API key with credit	Created in step 3. Usage is billed per token to the account that owns the key.
Internet access	To api.anthropic.com, and to PyPI during installation.

You don't need Node.js or the official Claude Code: the Claude Code engine is bundled with the claude-agent-sdk Python package that step 4 installs. You don't need sudo or admin rights either, except to install Python itself with apt on Linux.

Step 2: Install Python and Git

macOS. The Python that ships with macOS (3.9) is too old. Install a newer Python, and git, with Homebrew:

brew install python git

python3 --version

It must print 3.10 or newer. If it still prints 3.9, use Homebrew's Python by its full path in step 4: /opt/homebrew/bin/python3 (Apple Silicon) or /usr/local/bin/python3 (Intel).

Ubuntu / Debian. Ubuntu 22.04 and Debian 12 or newer ship a recent enough Python:

sudo apt update && sudo apt install -y python3 python3-venv git

python3-venv is required: without it, step 4 cannot create the virtualenv.

Windows 11. Open Terminal from the Start menu (Windows Terminal, which starts PowerShell) and install Python and Git:

winget install -e --id Python.Python.3.13

winget install -e --id Git.Git

Close the terminal and open a new one, so that py and git are found, then check that py --version prints 3.10 or newer.

• Use py (the Python launcher), not python: on a Windows without Python, python opens the Microsoft Store.
• Install Git for Windows even if you never use git yourself: Claude runs its commands through Git Bash when it finds it. Without it, Claude uses PowerShell, and its activity lines read PowerShell(…) instead of Bash(…).
• Windows on ARM (e.g. Snapdragon laptops): claude-agent-sdk only bundles the Claude Code engine for x64. Install the x64 build of Python, or install the engine with irm https://claude.ai/install.ps1 | iex. Step 4 tells you when the engine is missing.

Step 3: Create an Anthropic API key

1. Open the Claude Console and sign in, or sign up.
2. Add credit in the Console's billing settings. The API is pay-as-you-go, billed per token: the first turn in the screenshot above cost $0.0268 with Sonnet.
3. Open the API keys page, create a key (name it, for example, claude-code-mini) and copy it. It starts with sk-ant- and is shown only once, so keep the page open until you have saved it in step 6.

Treat the key like a password. Anyone who has it can spend your credit. Never commit it to git, and never paste it into a chat, an issue or a screenshot. If it leaks, delete it in the Console and create a new one.

claude-code-mini only works with an API key. It refuses to start without ANTHROPIC_API_KEY, and if the Claude Code engine reports any other login (such as a Claude Pro/Max subscription), it stops immediately, so your subscription is never used.

Step 4: Download and install

Choose where to keep the source code (your home folder is fine) and run, on macOS and Linux:

git clone https://github.com/imransetiadi/claude-code-mini.git
cd claude-code-mini
python3 claude-code-mini.py --setup

On Windows 11, in PowerShell:

git clone https://github.com/imransetiadi/claude-code-mini.git
cd claude-code-mini
py claude-code-mini.py --setup

--setup does everything in one go:

1. It creates a private virtualenv in ~/.local/share/claude-code-mini/venv (on Windows, ~ is %USERPROFILE%, for example C:\Users\budi).
2. It installs claude-agent-sdk, which bundles the Claude Code engine, plus rich and prompt_toolkit.
3. It copies the script to ~/.local/share/claude-code-mini/ and creates the claude-code-mini command in ~/.local/bin (claude-code-mini.exe on Windows).
4. It checks your PATH and your API key, and prints the exact command for anything still missing. On Windows it also checks the Claude Code engine and Git Bash.

Its messages are in Indonesian. On a fresh Ubuntu machine the output looks like this:

→ Membuat virtualenv di /home/dev/.local/share/claude-code-mini/venv …
→ Memasang claude-agent-sdk>=0.2.178, rich>=13, prompt_toolkit>=3.0.40, gnureadline; sys_platform == 'darwin' …
✓ Library terpasang (/home/dev/.local/share/claude-code-mini/venv)
✓ Perintah claude-code-mini dibuat (/home/dev/.local/bin/claude-code-mini → /home/dev/.local/share/claude-code-mini/claude-code-mini.py)
! ~/.local/bin belum ada di PATH. Jalankan ini (sekali saja):
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
! ANTHROPIC_API_KEY belum di-set. Tambahkan ke ~/.bashrc (key tidak tampil di layar):
    read -rsp "API key: " K; echo; echo "export ANTHROPIC_API_KEY=\"$K\"" >> ~/.bashrc; unset K; source ~/.bashrc

Coba: claude-code-mini /path/ke/repo
Versi baru (setelah git pull / edit claude-code-mini.py) dipasang dengan: python3 /home/dev/claude-code-mini/claude-code-mini.py --setup

Line	Meaning
→ Membuat virtualenv …, → Memasang …	Creating the virtualenv, installing the libraries.
✓ Library terpasang	The libraries are installed.
✓ Perintah claude-code-mini dibuat	The claude-code-mini command was created.
! ~/.local/bin belum ada di PATH. Jalankan ini (sekali saja):	~/.local/bin is not on your PATH yet; run this, once. See step 5.
! ANTHROPIC_API_KEY belum di-set. Tambahkan ke ~/.bashrc (key tidak tampil di layar):	The API key is not set; add it to ~/.bashrc (the key is not shown on screen). See step 6.
Coba: …	"Try: …", how to start it.
Versi baru (…) dipasang dengan: …	After a git pull or an edit, this command installs the new version.

✓ means done, ! means something is left for you to do, and ✗ means an error (see Troubleshooting). On Windows there are two more lines: ✓ Mesin Claude Code: claude.exe bawaan claude-agent-sdk ("Claude Code engine: the claude.exe bundled with claude-agent-sdk") and ✓ Git Bash: C:\Program Files\Git\bin\bash.exe (Claude menjalankan command lewat Bash) ("Claude runs commands through Bash").

The claude-code-mini command runs the installed copy, not the file in your clone. After a git pull, run --setup again (see Update and uninstall).

Step 5: Put the command on your PATH

Skip this step if --setup printed no PATH line. Otherwise run the command for your system, once.

macOS (zsh, the default shell):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Linux (bash):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Windows (PowerShell). This adds %USERPROFILE%\.local\bin to your user PATH, for this window and every new one:

$p = [Environment]::GetEnvironmentVariable("Path", "User"); [Environment]::SetEnvironmentVariable("Path", "$p;$HOME\.local\bin", "User"); $env:Path += ";$HOME\.local\bin"

Step 6: Save your API key

Run the command for your system, paste the key when it asks for API key:, and press Enter. Nothing appears while you paste: the key is read without echo, so it never shows on screen or in your shell history. The command saves the key for every new terminal and also loads it into the current one.

macOS (zsh):

read -rs "K?API key: "; echo; echo "export ANTHROPIC_API_KEY=\"$K\"" >> ~/.zshrc; unset K; source ~/.zshrc

Linux (bash; with bash on macOS, use ~/.bash_profile instead of ~/.bashrc):

read -rsp "API key: " K; echo; echo "export ANTHROPIC_API_KEY=\"$K\"" >> ~/.bashrc; unset K; source ~/.bashrc

Windows (PowerShell). This stores the key as a user environment variable:

$s = Read-Host "API key" -AsSecureString; $k = [Net.NetworkCredential]::new("", $s).Password; [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $k, "User"); $env:ANTHROPIC_API_KEY = $k; Remove-Variable s, k

Like any environment variable, the key is stored as plain text: in your shell's startup file (~/.zshrc or ~/.bashrc), or in your Windows user environment. Don't share or commit that file. To replace the key later, delete the export ANTHROPIC_API_KEY=… line and run the command again (on Windows, just run it again).

Step 7: Check that it works

On macOS and Linux:

claude-code-mini --help

echo "${ANTHROPIC_API_KEY:0:7}…"

On Windows:

claude-code-mini --help

$env:ANTHROPIC_API_KEY.Substring(0, 7) + "…"

The first command prints usage: claude-code-mini …, the second sk-ant-… (only the first 7 characters, so the key stays private). Finally, send one real request with the cheapest model to check the key end to end:

claude-code-mini -p "Reply with one word: hello" --model haiku

Claude's answer appears, followed by a ✓ Selesai ("done") line with the cost of the request. If you get an error instead, see Troubleshooting. You're ready.

Your first session

Open a terminal in a project folder and start claude-code-mini there. That folder becomes Claude's workspace: Claude may read anything inside it, and it asks before touching anything outside it.

cd ~/projects/my-app
claude-code-mini

You can also run claude-code-mini ~/projects/my-app from anywhere (on Windows, for example, claude-code-mini C:\projects\my-app). Without --model, the model is Opus (claude-opus-5-5), the most capable one; the screenshots below use --model sonnet, which is cheaper.

They come from a tiny Python project with a bug: kalkulator.py ("calculator") has a function bagi ("divide") that multiplies instead of dividing, and test_kalkulator.py tests it. Type what you want in plain words and press Enter. Any language works; the prompts here are in Indonesian, like the interface.

1. Ask, and answer permission questions

1. The banner shows the project folder (📂), the model and permission mode (🤖), and the shortcuts: ? help, ! shell command, @ attach a file, # save a note, Esc stops Claude.
2. › is your message. Here: "run the tests with python3 -m unittest -v, then fix whatever fails".
3. ✓ Terhubung ("connected") names the model and the mode, and auth: ANTHROPIC_API_KEY confirms that your API key is being used.
4. Each action is an activity line: ● Bash(…) runs a command, ● Read(…) reads a file, ● Update(…) edits one, and so on.
5. 🔐 Claude minta izin ("Claude asks for permission") appears before Claude runs a command. Type a number and press Enter (Enter alone means 1):
   • 1 Ya: yes, this once.
   • 2 Ya, dan jangan tanya lagi untuk Bash(python3 -m unittest -v): yes, and don't ask again for this command. The rule is saved in .claude/settings.local.json in your project.
   • 3 Tidak, dan beri tahu Claude harus bagaimana: no, and tell Claude what to do instead. You are asked for the instruction next.

2. Watch Claude work

1. Pilih [1/2/3, Enter=1] › 2: the answer was 2, so ✓ Aturan ditambahkan ("rule added"): from now on Claude may run this test command without asking.
2. The output of each command appears under it, after ⎿. Long output is cut short on screen (… +12 baris, "12 more lines"), but Claude receives all of it. Here, test_bagi fails.
3. Edits are shown as diffs. Claude read kalkulator.py and fixed it: ● Update(kalkulator.py) shows the changed lines with their line numbers (Ditambah 1 baris, dihapus 1 baris, "1 line added, 1 removed") and Tersimpan ("saved"). Edits inside the project are applied without asking, because the starting permission mode is acceptEdits. You still see every change, and /rewind undoes them.
4. Claude checks its work. It ran the tests again, without asking this time, and they pass. Then it explains: "One test failed: test_bagi. The bagi function in kalkulator.py used a * b (multiplication) … I changed it to a / b, and both tests now pass."
5. ✓ Selesai ("done") sums up the turn: 5 steps (langkah), 6.9 seconds (detik), 413 output tokens, the cost of this turn (biaya) and of the whole session so far (total sesi).
6. The toolbar under the empty prompt shows the permission mode (⏵⏵ auto-terima edit, "accept edits automatically", which Shift+Tab changes), the model, how full the context window is (konteks 2%), the session cost, and ? untuk bantuan ("? for help").

3. Type while Claude works

The prompt never locks. In this screenshot Claude is working on the next request, "add a test for division by zero, then run all the tests", and a follow-up, "pakai assertRaises ya" ("use assertRaises"), has just been sent:

1. The prompt stays at the bottom with the hint ketik pesan susulan… Enter = kirim (dibaca Claude setelah langkah ini) · Esc = hentikan: "type a follow-up… Enter = send (Claude reads it after this step) · Esc = stop".
2. The spinner line shows that Claude is working (Berpikir…, "thinking"), for how long, and the tokens so far. Esc or Ctrl+C stops the turn; the conversation is kept.
3. ⏳ dibaca Claude setelah langkah ini: … ("Claude reads it after this step"): a plain message is sent to Claude right away and read as soon as the running tool call finishes, so you can correct course without stopping Claude.
4. Commands wait their turn. /commands, !command and # note typed now run after the turn ends, shown as ⏳ setelah giliran selesai: … ("after the turn ends"). Press ↑ in the empty prompt to take a queued entry back.

Claude read the follow-up after its next step and replied that its new test already used assertRaises. All three tests passed, and the session cost $0.0410 in total.

4. Quit, and continue later

Press Ctrl+D, type /exit, or press Ctrl+C twice. claude-code-mini prints the total cost and the command that continues this conversation ("Total cost · Continue later with:"):

Total biaya: $0.0410 · Lanjutkan nanti dengan:
  claude-code-mini /home/dev/proyek/kalkulator --resume a1530349-b521-4b7a-995a-1e2efcdec637

You don't have to keep that ID: claude-code-mini -c continues the last conversation in the current folder, claude-code-mini -r lets you pick an older one from a list, and /resume does the same inside a session.

The browser GUI

Prefer a window to a terminal? Start it with --gui in your project folder:

claude-code-mini --gui

claude-code-mini starts a small server on your own computer (127.0.0.1) and opens the interface in your browser, as an app window when Edge or Chrome is installed. The terminal stays open and shows the address ("The browser is open. Keep this terminal open; Ctrl+C, or /exit in the GUI, stops it."):

✻ claude-code-mini GUI · 📂 /home/dev/proyek/kalkulator
  http://127.0.0.1:8765/?t=…
  Browser sudah dibuka. Biarkan terminal ini terbuka; Ctrl+C (atau /exit di GUI) untuk berhenti.

Everything works as in the terminal; only the presentation differs. The GUI follows your system's light or dark theme, and so do the screenshots below, which change with GitHub's theme.

The same first request in the GUI, waiting for permission.

1. Top bar: the project folder and five buttons: Baru ("new", a fresh conversation, like /clear), Riwayat ("history", shows or hides the history sidebar), Rewind (undo file changes), Bantuan ("help") and Keluar ("quit").
2. History sidebar (Riwayat obrolan): the conversations in the project folder, newest first, with the open one marked. Click one to continue it, or + Baru to start a new one. Each switch opens a clean page: a new conversation starts empty, and a continued one shows its own messages, answers and tool cards from the start, under its title. Reloading the page shows only the open conversation. The search box above the list filters it by title, and pointing at a conversation shows ✎ (rename) and 🗑 (delete, after a confirmation; the open conversation can't be deleted). To hide the sidebar, use the panel button at the top left, the ‹ button next to + Baru, or Ctrl+B (⌘B on a Mac); the choice is remembered. In a narrow window the sidebar slides in over the page.
3. The conversation: your messages are bubbles on the right, and each tool call is a card (here Bash with its command).
4. Permission questions are cards with buttons. Click one or press 1, 2 or 3. Choosing 3 ("Tidak", "no") opens a field for what Claude should do instead. While a question waits, the tab title shows 🔐.
5. Above the message box: what Claude is doing, for how long, and a ■ Stop button (Esc does the same).
6. Bottom bar: the permission mode and model selectors, the session cost (the context usage joins it after the first answer), and the connection status (terhubung, "connected").

The first turn finished; Claude is working on the second request, and a follow-up is waiting.

1. Tool cards show diffs in color with line numbers, and command output under the command. Long output is cut short, and Lihat output lengkap ("show full output") opens the rest.
2. Claude's answers are rendered as Markdown and stream in while Claude writes them (a blinking caret marks the end); ✓ Selesai sums up each turn, as in the terminal.
3. Copy buttons. Every code block in an answer has a copy button in its top-right corner (tooltip Salin kode · /copy 2), every answer has one underneath (Salin jawaban), and a command card (Bash) shows one when you point at it. The copied code has no Enter at the end, so pasting it into a terminal doesn't run it yet.
4. The message box stays usable while Claude works, with the same rules as in the terminal: the follow-up waits above the box (⏳ dibaca Claude setelah langkah ini) until Claude reads it after the current step.
5. Attachments. Click 📎 left of the message box, drag files onto the page, or paste an image or a screenshot with Ctrl+V. Each file shows as a chip above the box (× removes it); images get a thumbnail. When you send, the files are saved under ~/.local/share/claude-code-mini/uploads/ (up to 25 MB each, cleaned up after 14 days) and Claude reads them with its Read tool, which handles images, PDFs and text. Your bubble lists them.
6. Notifications. The 🔔 button in the bottom bar turns on a soft chime plus a browser notification (✓ Claude selesai, 🔐 Claude minta izin) for when Claude finishes or asks for permission while you are in another tab or window. The browser asks for permission the first time you send a message; click 🔔 to turn it off.

The end of the session: the follow-up appears where Claude read it, followed by Claude's answer and the totals.

Keys in the GUI:

Key	What it does
Enter / Shift+Enter	Send / new line
Esc	Stop Claude (same as the Stop button)
Shift+Tab	Switch the permission mode
Tab	Pick the /command or @path suggestion shown while typing
↑ in the empty message box	Bring back the last message you sent
Ctrl+B (⌘B on a Mac)	Show or hide the history sidebar
Ctrl+V with an image or file copied	Attach it
1 / 2 / 3	Answer the permission question on screen

Everything else, such as !command, @file, # note, /goal, /tasks, /model or /copy 2, is typed into the message box as in the terminal. Conversations from the GUI and the terminal are stored in the same place, so you can continue them either way. To stop, click Keluar, type /exit, or press Ctrl+C in the terminal. Reloading the page or opening a second tab does not interrupt anything.

Security. The GUI server only accepts connections from the same computer, and every request must carry the random token printed in the terminal (the ?t=… part of the address), so other web pages cannot drive it. Don't share the full address.

Use --port 9000 for another port (the default is 8765; if it is taken, the next free one is used). On a server, run claude-code-mini --gui --no-browser, connect with ssh -L 8765:127.0.0.1:8765 user@server from your own computer, and open the printed address in your browser.

Everyday use

Starting it

Command	What it does
claude-code-mini	Start in the current folder
claude-code-mini ~/projects/my-app	Start in another folder
claude-code-mini --model sonnet	Pick a model: opus (the default), sonnet, haiku, fable, or a full model ID
claude-code-mini --budget 5	Stop once the session has cost $5
claude-code-mini --mode plan	Plan first; Claude changes nothing until you approve the plan
claude-code-mini -c	Continue the last conversation in this folder
claude-code-mini -r	Pick an older conversation to continue
claude-code-mini -p "explain this repo"	One-shot: answer, then exit (for scripts and CI)
claude-code-mini -p "/goal all tests pass (pytest -q exits 0), at most 20 turns"	Keep working until the condition is met
claude-code-mini --gui	The same, in your browser
claude-code-mini --help	All options

Inside a session

Key or command	What it does
? or /help	Show help
!git status	Run a shell command; its output goes to Claude with your next message
@src/app.py	Attach a file or folder (Tab completes paths)
# always use pytest	Save a note to CLAUDE.md (project memory)
Shift+Tab	Cycle the permission mode: default → acceptEdits → plan
Enter while Claude works	Send a follow-up message mid-turn; Claude reads it after the current step. Commands wait until the turn ends
Esc or Ctrl+C	Stop Claude while it is working
\ at the end of a line, then Enter	New line (multi-line message)
↑ / ↓	Your earlier messages
/tasks, /stop 2	Watch or stop background agents and commands
/goal <condition>	Keep working until the condition is met (/goal shows status, /goal clear cancels)
/copy, /copy 2	Copy Claude's last answer, or code block 2 (see Copying answers and commands)
/rewind	Restore files to how they were before an earlier prompt
/resume, /clear	Switch to an older conversation (/resume ID goes straight to one), or start a fresh one
/model, /mode, /status, /cost, /context	Model, permission mode, session info, cost, context usage
Ctrl+D, /exit (or Ctrl+C twice)	Quit

Other Claude Code commands, such as /compact and /init, and your own .claude/commands/*.md are passed through to Claude Code.

Copying answers and commands

Selecting a command with the mouse often picks up the padding and broken lines of the screen. Instead, every code block in Claude's answers gets a number, shown under it in the terminal as a dim 📋 /copy 2:

• /copy 2 copies code block 2, exactly as Claude wrote it.
• /copy copies Claude's whole last answer (as Markdown).

Both work while Claude is still working, and the numbers stay the same for the whole session, even after /clear. On your own computer the text goes straight to the clipboard: pbcopy on macOS, the Windows clipboard, or wl-copy, xclip or xsel on Linux. Over SSH it is sent to your terminal as an OSC 52 sequence, which many terminals turn into a copy (for example Windows Terminal, kitty, WezTerm, and iTerm2 once clipboard access is allowed in its settings). Whether that worked can't be checked, so the text is then also printed plainly between two lines, ready to select with the mouse.

In the GUI, use the copy buttons on code blocks, answers and command cards, or type /copy or /copy 2 in the message box.

Permission modes

Mode	Toolbar	What Claude may do without asking
default	? tanya dulu sebelum edit & command ("ask before edits and commands")	Only read
acceptEdits (the starting mode)	⏵⏵ auto-terima edit ("accept edits automatically")	Read, and edit files in the project
plan	⏸ plan mode	Only read and plan. You then approve the plan with 1 (start, accepting edits), 2 (start, asking before each edit) or 3 (keep planning)
bypassPermissions (--yolo)	⚠ YOLO: tanpa izin ("no permission")	Everything. Use it only in a disposable sandbox

Shift+Tab cycles through the first three; --mode picks the starting mode. Commands you allowed with 2 are remembered per project in .claude/settings.local.json.

Scripts and CI

-p runs one prompt and exits. A permission question it cannot ask (no terminal) counts as "no". Exit codes:

Code	Meaning
0	Success
1	Error, budget exhausted, a permission prompt with no terminal to answer it, missing API key, or the engine failed to start
3	A /goal is unfinished, was refused, or was dropped after an error
130	Interrupted with Ctrl+C

What the Indonesian labels mean

On screen	Meaning
Terhubung · terhubung	Connected
Claude minta izin	Claude asks for permission
Ya · Tidak	Yes · No
jangan tanya lagi untuk …	Don't ask again for …
beri tahu Claude harus bagaimana	Tell Claude what to do instead
Pilih [1/2/3, Enter=1]	Choose (Enter = 1)
Aturan ditambahkan	Rule added
Membaca 16 baris	Read 16 lines
Ditambah 1 baris, dihapus 1 baris	1 line added, 1 removed
Tersimpan	Saved
… +12 baris	12 more lines (hidden on screen; Claude gets them)
Berpikir…, Menyusun…, Menimbang…	Claude is working ("thinking", "composing", "weighing"; the word changes)
esc untuk berhenti	Esc to stop
ketik pesan susulan…	Type a follow-up message…
dibaca Claude setelah langkah ini	Claude reads it after this step
setelah giliran selesai	After the turn ends
Dihentikan oleh user	Stopped by you
Selesai · 5 langkah · 6.9 detik · ↓ 413 token · biaya · total sesi	Done · 5 steps · 6.9 seconds · 413 output tokens · cost of this turn · session total
auto-terima edit	Accept edits automatically
konteks 2%	2% of the context window used
? untuk bantuan	? for help
Total biaya · Lanjutkan nanti dengan:	Total cost · Continue later with:
Baru · Riwayat · Bantuan · Keluar · Kirim	New · History · Help · Quit · Send (GUI buttons)
Lihat output lengkap	Show full output
Salin kode · Salin jawaban · Salin command · Disalin	Copy code · Copy answer · Copy command · Copied (GUI)
Riwayat obrolan · Cari percakapan… · Tidak ada percakapan yang cocok	Chat history (GUI sidebar) · Search conversations… · No matching conversation
Ganti nama · Hapus	Rename · Delete (GUI sidebar)
Lampirkan file · Lampiran dari user (baca dengan tool Read)	Attach a file · Attachments from the user (read them with the Read tool)
Claude selesai · Claude minta izin	Claude is done · Claude asks for permission (GUI notifications)
Versi baru claude-code-mini tersedia. Update dengan: claude-code-mini --update	A new version is out; update with claude-code-mini --update
clipboard tidak tersedia di sini, blok teks di bawah ini dengan mouse	No clipboard here; select the text below with the mouse

Update and uninstall

To update to the newest version, run:

claude-code-mini --update

It downloads the latest claude-code-mini.py from GitHub into the install folder, then updates the libraries (including the Claude Code engine) as --setup does. On Windows, close the other claude-code-mini windows first. You don't have to remember to check: about twice a day the app looks at GitHub in the background, and when a newer version is out it says so when it starts (⬆ Versi baru claude-code-mini tersedia. Update dengan: claude-code-mini --update) and in a strip at the top of the GUI, with a button that copies the command. Set CCMINI_NO_UPDATE_CHECK=1 to turn the check off.

Running the installer command again works too.

Installed by hand from a clone? --update updates the installed command but not your clone. To keep both in step, run these in the folder you cloned instead. On macOS and Linux:

git pull && python3 claude-code-mini.py --setup

On Windows (close any other claude-code-mini windows first, because Windows cannot replace files that are in use):

git pull; py claude-code-mini.py --setup

claude-code-mini --setup on its own only updates the libraries, for example to get the newest Claude Code engine bundled with claude-agent-sdk.

To uninstall on macOS and Linux:

rm -f ~/.local/bin/claude-code-mini ~/.claude-code-mini_history
rm -rf ~/.local/share/claude-code-mini ~/.config/claude-code-mini

On Windows:

Remove-Item "$HOME\.local\bin\claude-code-mini.exe*", "$HOME\.claude-code-mini_history" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$HOME\.local\share\claude-code-mini"

Then remove what still points to it:

• macOS and Linux: the block from # >>> claude-code-mini >>> to # <<< claude-code-mini <<< in ~/.zshrc, ~/.bashrc or ~/.bash_profile (after a manual install: the ANTHROPIC_API_KEY and PATH lines you added).
• Windows: the API key, with [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $null, "User").

Delete the cloned folder too, if you made one. Conversations are stored in ~/.claude/projects/, shared with the official Claude Code; delete them by hand if you want to.

Troubleshooting

Symptom	Cause and fix
claude-code-mini: command not found, or on Windows The term 'claude-code-mini' is not recognized…	The terminal was opened before the installation: open a new one, or run source ~/.zshrc (or ~/.bashrc). After a manual install, ~/.local/bin may not be on your PATH yet (step 5).
Installer: Key ditolak Anthropic (401) ("Anthropic rejected the key")	The key is mistyped, was deleted, or belongs to another workspace. Create a new one (step 3) and paste it again.
Installer: Key belum bisa dicek ("the key couldn't be checked yet")	The installer couldn't reach api.anthropic.com (no internet, a proxy or a firewall). The key is saved anyway; check your connection before starting.
Jalankan installer ini dengan bash ("run this installer with bash")	The script was piped into sh. Use … | bash, exactly as shown.
Windows: running scripts is disabled on this system	That happens when you run the downloaded install.ps1 file directly. Use the irm … | iex line, or powershell -ExecutionPolicy Bypass -File install.ps1.
ANTHROPIC_API_KEY belum di-set. ("not set")	The key is not set in this terminal. Repeat step 6, or open a new terminal.
An error about an invalid API key	The key is mistyped or was deleted. Create a new one (step 3), delete the old export line, and save it again.
An error saying your credit balance is too low	Add credit in the Claude Console's billing settings.
✗ Dihentikan: Claude memakai auth '…', bukan ANTHROPIC_API_KEY. ("stopped: Claude uses auth '…', not ANTHROPIC_API_KEY")	The engine is logged in another way, so claude-code-mini stops on purpose to keep your subscription out of it. Make sure ANTHROPIC_API_KEY is set in this terminal.
✗ Butuh Python 3.10 atau lebih baru ("needs Python 3.10 or newer")	Install a newer Python (step 2) and run --setup with it.
✗ Gagal membuat virtualenv ("failed to create the virtualenv"), or an error about ensurepip	Ubuntu/Debian: sudo apt install -y python3-venv, then run --setup again.
✗ pip install gagal ("pip install failed")	Check your internet or proxy access to PyPI, then run --setup again. On Windows with Access is denied: close other claude-code-mini windows first.
✗ Mesin Claude Code gagal start ("the Claude Code engine failed to start")	Check access to api.anthropic.com and that the key is valid, then update with --setup. The engine's own message is printed above.
⚠ Rate limit: …	Your account's API rate limit was reached. Wait a moment, or check your limits in the Claude Console.
python opens the Microsoft Store (Windows)	Use py, and install Python if needed (step 2).
Codes like ←[32m, or a broken-looking prompt (Windows)	Run it in Windows Terminal, not in the local terminal of MobaXterm or the separate Git Bash (mintty) window.
Windows: irm: command not found and iex: command not found	The Windows line was typed into a bash terminal (MobaXterm, Git Bash, Cygwin). Open PowerShell (Windows key, type PowerShell) and run it there. The macOS/Linux line, run in such a terminal, says the same.
Activity lines show PowerShell(…) instead of Bash(…) (Windows)	Git for Windows is not installed: winget install -e --id Git.Git, then open a new terminal.
Alt+Enter doesn't add a new line	End the line with \ and press Enter. (In Windows Terminal, Alt+Enter switches to full screen.)

The full tutorial lists more cases.

Full tutorial

The complete guide covers everything above in more depth, plus background agents, /goal, plan mode, CI usage, per-project configuration, running on a server over SSH, and every option, command and key:

• English
• Bahasa Indonesia

How it works

claude-code-mini is a UI and control layer on top of the Python claude-agent-sdk, which bundles the Claude Code engine:

you ─▶ claude-code-mini ─▶ Claude Agent SDK ─▶ Claude Code engine ─▶ Anthropic API
       (UI, permissions,   (Python library)    (bundled with the SDK)
        status, cost)

It only reads project-level settings (CLAUDE.md, .claude/settings.json, .claude/settings.local.json and .claude/commands/). Claude Code stores the conversations in ~/.claude/projects/.

Used on macOS and Ubuntu 26.04 (Python 3.13 and 3.14) with claude-agent-sdk 0.2.178 and 0.2.179 (Claude Code engine 2.1.318 and 2.1.319). The automated tests also run on Windows Server 2025, which shares its build with Windows 11 24H2 (see Tests).

Tests

Every push to main and every pull request runs the tests in GitHub Actions on Windows, Ubuntu and macOS, plus the oldest supported Python (3.10) on Ubuntu (workflow). The end-to-end tests run the real Claude Code engine against a small local fake of the Messages API (tests/fakeapi.py), so they need no API key and cost nothing. They cover --setup, -p mode and its exit codes, the interactive UI in a pseudo-terminal (permission prompts, typing while Claude works, Esc, Shift+Tab, !command and @file), and the GUI over HTTP. On Windows they also check a run without Git Bash.

The installers are tested the same way. install.sh and install.ps1 run in a pseudo-terminal, where the test types text that isn't a key, a key the fake API rejects, and then a valid one. The test then runs the installed command with only what the installer saved, and runs the README one-liner (curl … | bash or irm … | iex) as an update. install.sh is also run on fresh Ubuntu 22.04 and 26.04 containers that have no Python: as root it installs Python with apt-get, and as a user without sudo with uv.

To run them yourself, after --setup:

python3 -m venv .venv && .venv/bin/pip install pyte ptyprocess
.venv/bin/python tests/e2e.py
.venv/bin/python tests/gui.py
.venv/bin/python tests/install.py
~/.local/share/claude-code-mini/venv/bin/python tests/unit.py

On Windows, install pyte pywinpty instead, and use .venv\Scripts\python and %USERPROFILE%\.local\share\claude-code-mini\venv\Scripts\python.exe. The tests give the app its own HOME inside test-out/, so your prompt history and conversations are left alone. On Windows, tests/install.py only runs in CI (or with --force), because the installer writes to your user environment variables.

Notes

• API usage is billed to the Anthropic account that owns the key. Use --budget to cap a session.
• --yolo lets Claude run any command without asking. Use it only in a disposable sandbox.
• The screenshots in this README come from real sessions with Claude Sonnet; only the project folder's path was replaced with a generic one.
• Use of Claude is subject to Anthropic's terms.

License

Licensed under the Apache License 2.0. Copyright 2026 Imran Setiadi.