One file. Your AI knows the way.

A common guide for local AI clients

Your AI reads a startup instruction file and uses Studio’s local HTTP connection. The instructions are the same across clients. Only the filename and the place your editor loads it from vary.

You need KaKeKiKoKu Studio 1.17 or later and an AI client already installed. The AI must be able to run local tools that make HTTP requests, such as a terminal. Ordinary browser chat or an agent running on a remote machine cannot reach Studio on your computer through its own localhost.

Start KaKeKiKoKu Studio first, every time. Open it from your applications menu and leave it running while you work. This connection does not start Studio for you.

1. Add the instructions

Save the file where your AI client loads project instructions automatically, usually at the root of the folder you open in that client. If you already have an instruction file, append this section and keep your existing rules. Choose one Wuniq connection method for that workspace so startup rules do not ask for both HTTP and MCP.

• AGENTS.md is a common convention, including Codex.
• CLAUDE.md is the project instruction file for Claude Code.
• Another client? Use the filename, location, or always-on rule specified in your editor’s documentation. Use the same downloaded content there. A file named AGENTS.md only works if your client actually loads it.

Download AGENTS.md  ·  Download CLAUDE.md — identical content, different filenames.

Recommended: download the file directly. Save the original file instead of copying its text through a chat or document preview. Some copy-and-paste paths can alter quotes, slashes, or other characters and break the instructions. If you already have an instruction file, merge the downloaded content into it without replacing your existing rules, and check that the URL and quoted JSON examples remain intact.

The downloads use Studio’s default address, http://localhost:5050/api/agent. If you changed the port, replace that address in the file with the one your Studio uses. Keep it local.

# KaKeKiKoKu Studio — local HTTP access

The human starts KaKeKiKoKu Studio before the AI uses it. Use the local command
bridge at `http://localhost:5050/api/agent`. It runs on the same computer as Studio. An AI whose
shell runs in a container, remote host or separate sandbox may not reach this
loopback address; use a local execution tool with the necessary network permission.
Do not invent a tunnel, configure MCP, start another server, or change the port.
If Studio is unavailable, ask the human to start it and confirm its local address.

## Start of each conversation

1. Send an HTTP POST with `Content-Type: application/json` and this JSON body:
   `{"action":"initialize","protocolVersion":1,"client":"your IDE or agent name"}`.
2. Parse the JSON response and keep its `sessionId` for this conversation. `client` is an optional,
   self-declared label, not authenticated identity. Never initialize per command.
3. Run `open list` as the first command, using POST and JSON at the same URL:
   `{"action":"run","sessionId":"returned-id","command":"open list"}`.
   Use a JSON serializer; command quotes, backslashes and newlines need JSON escaping.
   The response is plain text. Read the body even when the HTTP status is not 200.
   Wait for each command before sending another that depends on it.
4. Next run `help` with the same `run` envelope, then open only projects returned
   by `open list` that this task needs.
   If the list is empty, proceed normally; the human may open projects later.
   Never assume the current working directory is a KaKeKiKoKu project.

Use an available local HTTP tool, or a shell with PowerShell `Invoke-WebRequest`,
Python's standard HTTP library, or `curl`. Keep normal tool permission checks.
There is no extra CLI or MCP process to install. Fetch only needed `help <topic>`
pages for the command language and reading rules. `initialize` reports request
and response limits; `maxResponseChars` counts UTF-16 code units in the command's
plain-text response. Respect these limits and follow the help for large results.
GET at the same URL returns discovery information; add `?instructions=agents` or
`?instructions=claude` to download these instructions for this Studio instance.

## Project knowledge

- `.wuniq` files: never use native Read/Edit/Write. Use `read`, `edit`, `new`, `search`.
- Before code work, read the folder sidecar first, then the relevant file sidecars.
- Capture human decisions, constraints and rationale in sidecars immediately.
- Use named subsections for distinct topics; append only to the same topic.
- After changing project files or context, run `sync` and follow its instructions.
- Use native tools for real project files. `read` retrieves knowledge, not source code.
- Coordinate edits with other clients and the human; do not write the same resource
  concurrently. Shared project state does not provide transaction isolation.
- For product or Web questions, run `help kakekikoku`. Use `current` for the human's
  Web view associated with projects opened by this conversation.

## Session recovery

Sessions expire after 24 hours without requests and whenever Studio restarts.
HTTP 410 with `SESSION_EXPIRED` means this request was not forwarded. Initialize
again, run `open list`, and open the projects still needed. Reads/project state are
shared with the Web and other clients, not isolated by this session identifier.
After a lost response, timeout or server restart, inspect the affected state before
repeating a mutation: the original command may already have completed. No retries
are performed by the bridge. Set the HTTP client's timeout to at least 610 seconds
for long commands; the bridge's execution timeout is 600 seconds.

At the end, optionally POST `{"action":"close","sessionId":"returned-id"}`.
This retires only the HTTP identity; accepted commands may still finish.
The language command `close` closes a shared
project and affects other clients; do not use it just to disconnect.

Studio must remain running. HTTP does not auto-launch it, provide background MCP
heartbeats/channel notifications, or expose development commands such as
`dev recompile`. Run `sync` at appropriate checkpoints to discover drift.
The local API trusts local processes; the session ID is not an authentication token.

If this file already contains project instructions, merge this section and preserve them.

No extra CLI, plugin, MCP configuration, or API key is needed for this local connection. Your AI client still uses its own account and normal tool permissions.

2. Start a new conversation and check

In Studio, open a project and make it available to AI. Then start a new conversation in the folder containing your instruction file. If your client asks for permission to use a local shell or contact Studio, review and allow the operation through its usual permission controls.

Ask your AI:

Which projects are available in KaKeKiKoKu Studio? Read the context of the project we are working on.

Check the tool activity: the AI should connect locally, run open list, and open and read the relevant project. An empty list means no projects are available to that conversation yet; it is not a connection failure.

Then work normally. The instructions tell the AI to read project context before changes and to run sync afterwards. You can also ask it to sync at any time.

What changes in daily use?

• Open Studio before starting work. Keep it running alongside your editor.
• Use Precise mode in Settings > Application. The AI checks changes through commands; this connection does not receive background MCP channel messages. More about sync.
• Your knowledge stays the same. You can use HTTP and MCP with the same projects. Coordinate edits if several clients work on the same resource.
• A restart is recoverable. If Studio restarts, the instructions tell the AI how to reconnect and check state before repeating a change.

Prefer an MCP tool connection, automatic app launch, or channels in a client that supports them? Follow the MCP setup guides. MCP remains available.

If it does not connect

• The AI ignores the file: check the required name and location in your client’s documentation, then start a new conversation. Check for conflicting Wuniq startup rules.
• Connection refused: open Studio and check its port. Use a version that includes local HTTP access; an older version may return “not found”.
• The browser can reach Studio but the AI cannot: its shell may run inside WSL, a container, a remote host, or a restricted sandbox. Use an execution environment that can reach the same local Studio instance and review the client’s network permissions. Do not expose Studio to the internet.
• A command failed: ask the AI to read the response and the relevant help topic. The same command help is available through both connections.

The filename is a convention, not a compatibility guarantee. The first-use check above confirms what your client actually does.