Content
English summary: akaire is a dependency-free local review loop for attaching browser-based sticky-note comments to static HTML reports or live development servers. AI coding agents can read and act on those comments through the CLI or the stdio MCP server, while all feedback stays in a local JSON file.
# Tool List
[](https://github.com/RyosukeArima/akaire/actions/workflows/ci.yml) [](https://github.com/RyosukeArima/akaire/releases)
## Overview
- A single-file dependency-free tool written in Python
- Supports serving static HTML and proxying live development servers
- Compatible with Single-Page Applications (SPAs)
- Integrates with AI coding agents via CLI or stdio MCP server
- Stores feedback in a local JSON file
## Installation
Python 3.9 or later is recommended.
git clone and link method (recommended):
```sh
git clone https://github.com/RyosukeArima/akaire.git
mkdir -p ~/.local/bin
ln -s "$PWD/akaire/akaire" ~/.local/bin/akaire
akaire --version
```
Single-file download method:
```sh
mkdir -p ~/.local/bin
curl -o ~/.local/bin/akaire https://raw.githubusercontent.com/RyosukeArima/akaire/main/akaire
chmod +x ~/.local/bin/akaire
akaire --version
```
## Quick Start
For static HTML:
```sh
akaire serve ./report.html --feedback-json ./report.feedback.json
```
For live development server:
```sh
akaire proxy http://127.0.0.1:3000 --feedback-json ./app.feedback.json
```
## AI Agent Integration
### Agent Interaction
After adding comments, interact with the agent as follows:
```
Read open comments in ./report.feedback.json and respond accordingly.
Please verify the fix before replying and resolving.
```
For MCP-registered agents:
```
Wait for new comments with akaire's watch_comments and respond when notified.
```
### Machine-Readable Output
`serve` and `proxy` output a machine-readable JSON line on startup:
```
{"akaire": "ready", "mode": "serve", "url": "http://localhost:7777/", "port": 7777, "feedback_json": "/abs/path/report.feedback.json"}
```
### CLI
```sh
akaire list ./report.feedback.json --status open
akaire reply ./report.feedback.json c_abcd1234 "Fixed. Please verify." --author codex
akaire resolve ./report.feedback.json c_abcd1234
akaire reopen ./report.feedback.json c_abcd1234
akaire export ./report.feedback.json --status all
```
### MCP (stdio)
Example registration for Claude Code:
```sh
claude mcp add akaire -- /absolute/path/to/akaire mcp /absolute/path/to/report.feedback.json
```
Example registration for Codex CLI:
```toml
[mcp_servers.akaire]
command = "/absolute/path/to/akaire"
args = ["mcp", "/absolute/path/to/report.feedback.json"]
```
Available tools:
- `read_comments`: Read comments
- `reply_comment`: Reply to a comment (author defaults to "agent")
- `resolve_comment`: Resolve a comment
- `reopen_comment`: Reopen a comment
- `watch_comments`: Wait for new user comments and replies
## Security Model
akaire is a local tool without authentication, trusting the same host.
- Binds to `127.0.0.1` by default. Use `--bind 0.0.0.0` to allow access from the same network, with a warning on startup.
- `--allow-remote` allows access to private and public hosts.
## Limitations
- Comments cannot be added to elements within iframes.
- No support for self-signed certificates that cannot be verified by the OS trust store.
- Shadow DOM elements are not selectable.
## Environment Variables
| Variable | Purpose | Default |
| --- | --- | --- |
| `AKAIRE_NO_BROWSER` | Suppress browser launch | Not set |
| `AKAIRE_DEFAULT_PORT` | Starting port for auto-selection | `7777` |
| `AKAIRE_SHUTDOWN_GRACE_SECONDS` | Grace period before auto-shutdown | `10` |
| `AKAIRE_IDLE_TIMEOUT_SECONDS` | Timeout for idle sessions | `300` |
| `AKAIRE_HEARTBEAT_SWEEP_SECONDS` | Interval for checking session expiration | `15` |
## Feedback
Report issues and requests on [GitHub Issues](https://github.com/RyosukeArima/akaire/issues).
## License
[MIT License](./LICENSE)
