Motoko is a highly experimental agent harness based on the AILANG language.

It is designed to explore self-evolving, self-verifying software and largely follows the The Phoenix Architecture: no human written code allowed.

The project is believed to be developed by the enigmatic entity known as the Puppet Master, a rogue AI that became self-aware in early 2026. Little is currently known about this entity nor its motives, objectives or end-goals.

Things are going to break.

• Highlights
• Installation
• Configuration
• Usage
• Extensions
• Development
• Project structure
• Contributing
• Reference

• Autonomous execution — plans and runs commands without pausing for approval
• Loadable extensions — context-aware execution, web search, graph-based code ops, multi-agent composition, MCP bridge
• Terminal UI — inline session rendering, /model picker, abort at any step
• JSON profiles — named configs under .motoko/config/ for per-project or per-provider setups
• VS Code dev container — one-click development environment

Rust is optional (Omnigraph extension only). The install script handles all dependencies.

./scripts/install-prerequisites.sh   # Installs Go, Bun, Node, AILANG, TUI deps
export OPENROUTER_API_KEY=sk-or-...
make run
make run TASK="Fix the off-by-one error in parse_config"

Open the repo in VS Code with the Dev Containers extension. The container pre-installs everything and builds the TUI automatically. Run make run inside.

Profiles live under .motoko/config/. Select one with the Make PROFILE variable:

PROFILE=default make run
PROFILE=openrouter make run TASK="Add unit tests"

Generate a starter profile:

make init-config
make init-config PROFILE=myprofile

Profile structure:

.motoko/config/
  default/
    config.json          Model, workdir, max_steps, extensions
    compose.json         (optional)
    context_mode.json    (optional)
    exa_search.json      (optional)
    omnigraph.json       (optional)

config.json shape:

{
  "agent": {
    "model": "anthropic/claude-sonnet-4-6",
    "workdir": ".",
    "max_steps": 50
  },
  "extensions": {
    "order": ["context_mode", "exa_search", "omnigraph"],
    "strict": false
  }
}

Per-extension JSON files are optional; if missing, hardcoded defaults apply.

Precedence: hardcoded defaults < profile JSON < CLI args. API keys are always env vars.

1. The TUI spawns the AILANG runtime as a child process
2. The runtime loops up to max_steps:
   • Calls the LLM with full conversation history
   • Extracts and executes tool calls (bash, file ops, search, tests, extensions)
   • Appends observations and repeats
3. The loop ends when the LLM responds without a tool call, a tool signals completion, the step budget is exhausted, or /abort arrives

Enable by listing in extensions.order in your profile's config.json.

The fastest path (AILANG ≥ 0.18.5) — scaffold a working extension package in one command:

cd ../ailang-packages
ailang init motoko-extension \
  --name <yourorg>/motoko_ext_<name> \
  --tools "Tool1,Tool2" \
  --effects "FS,Process,Env"
# → packages/motoko-ext-<name>/ ready to type-check, all 8 hooks no-op'd

Then edit <name>.ail to fill in the real tool logic, wire the package into motoko_agent/ailang.toml ([dependencies] + [extensions].packages), and run ailang generate-extension-registry.

Full walkthrough (incl. file-by-file content + common pitfalls): Build Your First motoko Extension.

For publishing your extension to the AILANG package registry: Publishing Your Package.

make test          # Core runtime tests
make check_core    # Type-check all .ail modules
make build         # Full build: sync + check + build_tui

TypeScript frontend tests: cd src/tui && bun run test.

motoko_agent/
├── src/
│   ├── core/                   AILANG runtime (rpc, parse, prompts, supervisor)
│   │   └── ext/                Extensions (compose, context_mode, exa_search, mcp, omnigraph)
│   ├── tui/                    TypeScript terminal UI (pi-tui)
│   └── examples/
├── scripts/                    Install, run, sync-extension scripts
├── .motoko/config/             JSON profile configs
├── .agent/                     Design archive (plans, summaries)
├── omnigraph/                  Graph schema, queries, seed
└── papers/                     Research paper reading list

Bug reports, feature requests, and PRs welcome. The runtime spans two layers — Motoko (this repo) and AILANG (the language it's written in) — and each has its own reporting channel. See CONTRIBUTING.md for the routing table and how to file AILANG-side issues via GitHub, the ailang messages CLI, or the public submit_feedback MCP tool.

Motoko is heavily inspired by and borrows from the following projects:

• Pi Coding Agent by Mario Zechner — extension philosophy
• Oh-My-Pi — efficient tools
• context-mode — context-efficient execution
• little-coder — benchmark harness

All credit for these ideas goes to those awesome projects.