{"id":49617745,"url":"https://github.com/im-knots/ainulindale","last_synced_at":"2026-05-04T23:45:51.916Z","repository":{"id":335182539,"uuid":"1143650317","full_name":"im-knots/ainulindale","owner":"im-knots","description":"A board game interface for real-time orchestration of persistent agent swarms","archived":false,"fork":false,"pushed_at":"2026-01-29T02:49:39.000Z","size":2425,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T13:50:43.723Z","etag":null,"topics":["agent-swarms","agentic-ai","agents","emergent-behavior","llm","llm-orchestration","rust","sandbox","strategy-game","typescript","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/im-knots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-27T20:54:21.000Z","updated_at":"2026-01-29T02:49:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/im-knots/ainulindale","commit_stats":null,"previous_names":["im-knots/ainulindale"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/im-knots/ainulindale","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-knots%2Fainulindale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-knots%2Fainulindale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-knots%2Fainulindale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-knots%2Fainulindale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/im-knots","download_url":"https://codeload.github.com/im-knots/ainulindale/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/im-knots%2Fainulindale/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32629703,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-swarms","agentic-ai","agents","emergent-behavior","llm","llm-orchestration","rust","sandbox","strategy-game","typescript","vibe-coding"],"created_at":"2026-05-04T23:45:46.632Z","updated_at":"2026-05-04T23:45:51.909Z","avatar_url":"https://github.com/im-knots.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ainulindale\n\n**Note:** This project is in very early stages of development. Morgoth hasn't been defeated yet. \n\nAinulindale [eye-new-lin-dah-lee] (or Ainu for short) is a board game interface for real-time orchestration of persistent agent swarms. It attempts to move beyond traditional chat-based interactions, 20 terminal windows, or flowcharts to a spatial management system where developer intent is expressed through the topology of a hex grid.\n\n![Ainulindale](./docs/img/screenshot.png)\n\n## Third Wave Vibe Coding\n\nAinulindale is designed for high-leverage, 10% attended operations. It treats agents as independent actors governed by the physics of the board rather than centralized orchestration.\n\nThe system visualizes AI workflows as a hex grid board game. Users place Agents and Tools on the board to add them to the simulation. Physical position on the board implies relationships according to RBAC settings for each tool entity. By decoupling agents from the board's global state, the system enables emergent behaviors and complex feedback loops.\n\nInstead of adding guard rails to prevent feedback loops, conflicting operations, and other \"accidents\", Ainulindale embraces them. Interesting and productive emergent behavior is the goal. With this level of freedom comes great responsibility. It is up to the user to design boards that achieve the desired outcomes.\n\nAinulindale is opinionated when it comes to how application layer chain of thought is created and maintained. The engine enforces a stateless, functional approach to intelligence. Models perform best on well-defined, atomic tasks with high-density context. Therefore:\n- Every new work item triggers a complete context rebuild from an empty state.\n- Tokens are spent finding relevant information via local RAG and tools to ensure the agent's thought process remains tight and focused.\n- This prevents context poisoning and logical drift common in long-lived persistent sessions.\n\nTokens spent reconstructing the agents context for each task can theoretically offset the need for expensive memory tokens. The goal of this pattern is to distil long-throw, multi-shot \"intent\" into small, short-throw zero-shot tasks.\n\n## Core Concepts\n\n### Adjacency and Range of Effect\nAccess is determined by the \"Range of Effect\" slider and directional zones.\n- **Hexes**: Processing slots for Agents or Tools.\n- **Adjacency**: Entities within a tool's range automatically gain access based on their directional orientation.\n- **Scaleable Range**: Permissions are treated as a field. A single tool can radiate access to a local cell (Range 1) or an entire department (Range 3+).\n\n### Equippable Rulesfiles\nAgents are configured via a modular inventory system. Instead of static prompts, agents use \"equippable\" rulesfiles, markdown-based standards for specific languages, architectures, or workflows. This allows for hot-swapping agent personalities without reconfiguring the board.\n\n### Dynamic System Prompt Generation\nThe system prompt is JIT-compiled for every task iteration. The BoardRunner assembles a 7-section prompt:\n1. Environment (Identity, Platform, Workspace)\n2. Tool Definitions (Filtered by RBAC)\n3. Behavioral Guidelines\n4. Role Guidelines (Template-specific)\n5. Task Completion Protocols\n6. Equipped Rulefiles (Modular inventory)\n7. Custom User Instructions\n\n## Entity Types\n\n### Agent Providers\n\nAinulindale uses the **Vercel AI SDK** for unified LLM access with native function calling. This allows you to use any LLM provider or model that you like. Some models are better than others for certain tasks. Ainulindale lets you configure what provider to use for what agent rather than obfuscated model routers. The currently supported providers are:\n\n- **OpenAI** \n- **Anthropic** \n- **DeepSeek**\n- **Google Gemini** \n- **Cohere** \n- **Mistral** \n- **Ollama** \n- **Grok (xAI)** \n\n### Tool Providers\n\nTools provide capabilities for agents. These built in tools use a rust backend to provide the necessary OS level functionality. The currently supported tools are:\n\n- **Filesystem** - Sandboxed file access (read, write, list, search, codebase search)\n- **Shell** - Execute shell commands\n- **Tasklist** - In-memory task queue with pull-based claiming\n\n## Technical Features\n\n### Event-Driven Architecture\nHex entities run as persistent actors on a central event bus.\n1. **Emission**: Tools emit events (filesystem.changed, tasks.available).\n2. **Subscription**: RBAC controls which agents can consume which events.\n3. **Reaction**: Agents wake up and claim work items based on events occurring within their permitted zones.\n\nThis creates a self-organizing swarm where data flows through the grid based on the spatial layout rather than hard-coded logic.\n\n### Codebase Search (RAG)\nThe local RAG system provides semantic code search:\n- **Tree-sitter Parsing**: Chunks code into complete semantic units (functions, classes, structs).\n- **Local Embeddings**: FastEmbed (AllMiniLM-L6-v2) for private, zero-latency inference.\n- **Vector Storage**: Per-hex isolation using sqlite-vec.\n\n### Token Tracking and Heat Maps\nThe system provides visual guardrails:\n- **Two-Tier Tracking**: Monitor lifetime token totals and per-run usage.\n- **Hex Height Visualization**: Hexes grow in height during execution based on token usage, creating a real-time heat map of swarm activity.\n- **Automatic Cutoffs**: The board stops automatically when token limits are exceeded.\n\n### Plugin-Based Tools\nTools are implemented as self-describing plugins that register with a central registry:\n- **Self-Registration**: Plugins declare their own identity, configuration schema, and available tools.\n- **Auto-Generated UI**: Configuration panels are derived from JSON Schema - no hardcoded forms.\n- **Zod Validation**: Tool parameters use Zod schemas for type-safe AI SDK integration.\n- **Lifecycle Hooks**: Plugins can implement `initialize`, `dispose`, and `healthCheck` for resource management.\n- **Environment Awareness**: Plugins declare availability (e.g., Tauri-only tools won't appear in browser).\n\nAdding a new tool type requires only implementing the `ToolPlugin` interface and calling `pluginRegistry.register()`.\n\n## Development\n\n```bash\ngit clone https://github.com/im-knots/ainulindale.git\ncd frontend\n\n# Install deps\nnpm install\n\n# Run tests\nnpm run test           # Unit tests (Vitest)\nnpm run test:watch     # Watch mode\n\n# Type checking\nnpx tsc --noEmit\n\n# Run dev server\nnpm run tauri:dev\n\n# Build\nnpm run build\nnpm run tauri build    # Native app\n```\n\n## Tech Stack\n\n- **Frontend**: React, TypeScript, Vite, Three.js\n- **Desktop**: Tauri v2 (Rust backend)\n- **LLM**: Vercel AI SDK (multi-provider)\n- **Storage**: SQLite (via Tauri), sqlite-vec (vector search)\n- **Embeddings**: FastEmbed (AllMiniLM-L6-v2, local inference)\n- **Parsing**: Tree-sitter (syntax-aware code chunking)\n- **Testing**: Vitest (unit), Playwright (E2E)\n\n## Documentation\n\n**[Getting Started](docs/getting-started.md)** - Learn how to play the game\n\nSee the `docs/` directory for detailed documentation:\n\n- [Agents and Tools](docs/agents-and-tools.md) - Entity types, templates, and operations\n- [RBAC System](docs/rbac-system.md) - Zone patterns and permissions\n- [Budget System](docs/budget-system.md) - Token tracking and limits\n- [System Prompt Generation](docs/system-prompt-generation.md) - Dynamic prompt composition\n- [Agent State](docs/agent-state.md) - Chain of thought and context construction\n- [Board Execution](docs/board-execution.md) - Event system and actor lifecycle\n- [Codebase Indexer](docs/indexer.md) - RAG-powered semantic code search\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fim-knots%2Fainulindale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fim-knots%2Fainulindale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fim-knots%2Fainulindale/lists"}