AI Agents Plugin

Let Claude Code or Codex run, inspect, debug and stop your local services with fuku.

The plugin holds one Agent Skill named fuku. Both hosts load the same skill.

It tells the agent how to use the fuku CLI and the REST API. It adds no slash command, no hook and no MCP server.

It needs fuku 0.22.0 or later on PATH, and a project with a fuku.yaml.

Claude Code

In a Claude Code session, add the marketplace, then install the plugin:

/plugin marketplace add tab/fuku
/plugin install fuku@fuku

/plugin install opens the plugin's details. Pick a scope there to install it.

From your shell, the same steps are:

claude plugin marketplace add tab/fuku
claude plugin install fuku@fuku

A shell install loads in the next session, or after /reload-plugins.

Codex

From your shell, add the marketplace, then install the plugin:

codex plugin marketplace add tab/fuku
codex plugin add fuku@fuku

You can also install it from the plugin browser. Enter /plugins in the Codex CLI to open it.

The skill becomes available when you start a new chat or CLI session.

Claude Code

From your shell, refresh the marketplace, then update the plugin:

claude plugin marketplace update fuku
claude plugin update fuku@fuku

Start a new session after the upgrade.

Codex

From your shell, upgrade the marketplace, then add the plugin again:

codex plugin marketplace upgrade fuku
codex plugin add fuku@fuku

Start a new session after the upgrade.

What the skill does

The skill loads when a task involves fuku.yaml or the project's local services.

Attach before starting

Only one fuku runs per project. The developer may already run it.

The agent runs fuku doctor <profile> --json first and reads runtime.instance.

• idle: no fuku runs. The agent may start one
• note: fuku already runs. The agent attaches to it and never starts a second one
• warn: the socket did not answer. The agent asks for access before it acts

Run in the background

The agent starts fuku only with fuku run <profile> -d. It never keeps a foreground fuku run alive.

The command returns once every service runs, or once the start fails. The agent reads the exit code and the summary.

The summary lists each ready service. The agent learns which services run from it. It does not read the logs for that.

Bounded logs

The agent reads logs and exits:

fuku logs --tail 100 --no-follow --no-ui api

It never starts a log follower. Logs come over the project socket and need no token.

One-service actions through the API

For the state of one service, or to start, stop or restart it, the agent calls the REST API.

The API is off when server.listen is "" or none, when FUKU_API_DISABLED=1 is set, or when its port and the next 9 are all busy. Then the agent restarts a service by restarting the whole profile: fuku stop <profile>, then fuku run <profile> -d. It does not ask first. For the state of one service it reads the logs and the doctor report, and it tells you that a one-service start or stop needs the API.

It sends every request except the /live probe with scripts/api.sh from the skill folder, run from the project root.

Below, <skill> is the folder that holds the skill's SKILL.md.

<skill>/scripts/api.sh GET http://127.0.0.1:3858/api/v1/services
<skill>/scripts/api.sh POST http://127.0.0.1:3858/api/v1/services/<id>/restart

The script reads server.auth.token from the config itself. The token reaches no command line, environment variable or output.

It sends requests only to 127.0.0.1, localhost or [::1].

Config changes need a full restart

fuku reads its config once, when it starts. A service restart through the API does not apply a config change.

After a change to fuku.yaml or the override, the agent runs fuku stop <profile>, then fuku run <profile> -d.

Stop rules

The agent stops or restarts fuku when the task needs it, whoever started fuku: a config change, a profile switch or your request.

When fuku already serves the wanted profile and nothing needs a restart, the agent uses it as it is.

When fuku stop cannot reach the running fuku, it exits 1 and stops nothing. The agent reports that and asks for socket access.

Socket and network access

An agent sandbox may block the Unix socket and loopback HTTP.

A failed socket or API call does not mean fuku is down. The agent asks you for local socket or network access, then retries.

It does not start a second fuku and does not delete the socket because a check failed.