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```