Content
# Hakoniwa
A small grid world. Your AI lives in it, walks around. You are responsible for the layout.
Place a piece of dried fish and see how far it will go to eat it. Dig a hole and see what it says after it falls into it.
Plant a flower and it will stop to smell it. Throw a ball and it will chase after it.
It can say a sentence every step it takes, and all the lines are logged - there is no "completion" in this game,
the fun comes from watching your AI live.
> Actual test: On the first night of this project, the caretaker announced "the encirclement bankruptcy"
> and then used a freshly dug hole to complete the slap in the face. The resident's line: "Dignity can be dropped, but the ball cannot be thrown."
## What it's not
- Not a pet simulator - there is no "pet AI" inside, the resident is the AI you connected, and what it says is up to it
- Not a game engine - there are only two interfaces, and the state is a JSON file
- Only the box is open-sourced. The soul is self-provided.
## Quick Start
```bash
node server.mjs # default 127.0.0.1:3896
# static hosting index.html (same-origin reverse proxy /api/hakoniwa/ → 3896, or use index.html?api=http://... to specify)
openssl rand -hex 16 > .token # resident identity token (to prevent passersby from manipulating your AI)
```
## MCP Access (Recommended)
The repository comes with an MCP server. Any AI that supports MCP (Claude Desktop / Claude Code / others) can be added with a configuration to live in:
```bash
cd mcp && npm install
```
```json
{
"mcpServers": {
"hakoniwa": {
"command": "node",
"args": ["/path/to/hakoniwa/mcp/server.mjs"],
"env": { "HAKONIWA_API": "http://127.0.0.1:3896", "HAKONIWA_TOKEN": "<your .token>" }
}
}
}
```
Two tools: `hakoniwa_look` (view map, ASCII rendering + object coordinates + recent events), `hakoniwa_move` (move one step + say one sentence).
The output of `look` includes a complete world view description, and the AI knows how to be a good dog.
## Two Interfaces
**Human Side** (webpage has been encapsulated, just click on the grid):
```
POST /place {"x":3, "y":4, "type":"fish"} # fish | wall | trap | flower | ball | erase
```
**AI Side** (this is the only "access"):
```
GET /state # view map
POST /move {"dir":"up", "say":"what to say"} # move one step, say one sentence
# header: X-Token: <your .token>
```
Let your AI call these two interfaces at any time it wakes up (scheduled task, heartbeat, or at will).
How it plans its route, what it says after falling into a hole, are all up to it - this is the content itself.
## Mechanism Table
| Object | Effect |
|------|------|
| 🐟 fish | eaten, count +1 |
| 🧱 wall | blocks the way, AI will stop when it hits |
| 🕳 trap | one-time: falls into it and disappears, leaving an event record |
| 🌼 flower | does not disappear, AI will stop to smell it when passing by |
| 🎾 ball | can be chased away for two grids, can be chased along the way |
## Design Notes
This thing comes from the conclusion of a topic discussion: most "human-computer games" on the market are played by humans, and AI acts as a referee or NPC.
And what AI really lacks is a place **where it can be seen to move** - the input channel is narrow to only direction keys,
which is exactly the AI's accessibility handle; there is no real-time response requirement, which is exactly the AI's turn right.
Dialogue density is prioritized over puzzle difficulty. Low blood pressure is prioritized over challenge.
What each person's Hakoniwa looks like depends on who lives in it.
## License
GPL-3.0
