saki-io 0.1.0

Saki AI — Live2D avatar app with Copilot/Cursor CLI relay (ACP)

saki.io

Saki AI — Live2D avatar app with Copilot/Cursor CLI relay. Planning and goals live in MySpace; this repo is implementation only.

Install

uv sync

Run

uv run saki.io

Then open http://localhost:8000 in your browser. The app uses the Copilot CLI (e.g. brew install copilot-cli) and agent-client-protocol for context across messages. If ACP isn't available, the server falls back to one-shot copilot --prompt "...".

Commands for developers

All commands use UV:

Command	Description
uv run saki.io	Run Saki (default).
uv run saki.io --allow-tools	Allow Copilot to run commands, read/write files, and use tools (e.g. gh).
uv run saki.io -v	Enable verbose output (session, HTTP, ACP logs).

Flags can be combined, e.g. uv run saki.io --allow-tools -v.

Structure

• saki/io/ — Python package
  • server.py — HTTP server + setup APIs + /api/send → agent backend
  • app/ — static web app (HTML, CSS, JS) shipped as package data
  • backend/ — agent backend abstraction (Copilot now; Cursor later)
  • acp_client.py — Copilot ACP client (used by CopilotBackend)
  • bootstrap.py — .saki.io folder bootstrap
• tests/ — pytest

Stack

Plain HTML + JavaScript, no build. Python deps in pyproject.toml. Relay uses one copilot --acp --stdio session when agent-client-protocol is installed.

Tests

uv sync --extra dev
uv run pytest tests/ -v

Integration test (Copilot + gh): RUN_ACP_INTEGRATION=1 uv run pytest tests/test_acp_gh_integration.py -v

Debugging ACP

If you see "Using one-shot --prompt" and want the single-session (context) mode:

1. Install the ACP client: uv sync
2. Ensure Copilot supports ACP: copilot --acp --stdio (then Ctrl+C)
3. Run with verbose logs: uv run saki.io -v — startup and ACP errors are printed to stderr.
4. To inspect the raw ACP protocol: SAKI_ACP_LOG=1 uv run saki.io -v — every JSON-RPC message to/from Copilot is printed.

"Failed to list models" — Copilot ACP can't list models (auth/network). Start the server from a terminal where copilot --prompt "hi" works (same env = same credentials).

Tool use

By default, Saki rejects all tool use (terminal, file read/write). To allow Copilot to run commands and use tools:

uv run saki.io --allow-tools

Why does Saki say "tool rejected" when gh/copilot work in tests?

Tests run commands directly in the server process. In chat, Copilot uses the ACP flow: it asks for permission (we say "allowed"), then it calls back into our client. If that follow-up uses a method or param shape we don't support, we return "method not found". With SAKI_ACP_LOG=1 uv run saki.io -v you can see the exact ACP messages and adjust acp_client.py or backend.