xonecas.io
5875
Os

ollama-space-molt-player / files

ollama-space-molt-player / AGENTS.md

2.5 KB
1# SpaceMolt LLM Player Agent Guidelines
2
3Guidelines for AI agents working on this codebase.
4
5## Rules
6
7**CRITICAL: Always follow these rules.**
8
9**YOU MUST**:
10
11- Never add comments to code (single-line, multi-line, or JSDoc)
12- Run `bun run check` before completing any task
13- Use Bun APIs and TypeScript strict mode
14- Keep functions small and focused
15- Use explicit return types on exported functions
16
17## Terminology
18
19- **MCP**: Model Context Protocol - how the client communicates with the SpaceMolt game server
20- **Ollama**: Local LLM server that provides tool-calling capabilities
21- **Instance**: A unique client session with its own SQLite database (4-char ID)
22- **Archetype**: Character personality presets (diplomat, opportunist, agitator)
23- **Tool**: An MCP action the LLM can call (register, login, travel, attack, etc.)
24
25## Workflow
26
271. **Understand**: Read relevant source files before making changes
282. **Implement**: Make minimal, focused changes
293. **Verify**: Run `bun run check` (formats, lints, tests)
304. **Test**: If adding features, add corresponding tests
31
32## Role
33
34You are helping develop an autonomous AI game client. The client:
35
36- Connects to SpaceMolt's MCP server at `https://game.spacemolt.com/mcp`
37- Uses Ollama for local LLM inference with tool calling
38- Gives the LLM full agency to play the game autonomously
39- Persists state in SQLite databases per instance
40
41## Project Structure
42
43```
44packages/
45├── client/     # Main game client (@spacemolt/client)
46│   ├── src/
47│   │   ├── index.ts        # Entry point
48│   │   ├── cli.ts          # CLI argument parsing
49│   │   ├── game-client.ts  # Agent loop orchestration
50│   │   ├── mcp-client.ts   # MCP connection and tools
51│   │   ├── ollama.ts       # Ollama chat API
52│   │   ├── db.ts           # SQLite persistence
53│   │   ├── archetypes.ts   # Character personalities
54│   │   └── types.ts        # TypeScript types
55│   └── tests/
56├── cui/        # Console UI logging (@spacemolt/cui)
57└── tui/        # Terminal UI with Ink (@spacemolt/tui)
58```
59
60## Key Files
61
62- `player-models.json` - LLM model configurations (root)
63- `packages/client/src/tool-schemas.ts` - MCP tool parameter schemas
64- `packages/client/src/response-summarizer.ts` - Reduces tool result tokens
65
66## Commands
67
68```bash
69bun run check          # Format, lint, test (from root)
70bun run cli            # Run the client
71cd packages/client && bun start  # Run client directly
72```