doot

Public snapshot. This is a history-free snapshot of my personal AI companion runtime (developed privately; 800+ commits). Personal data, instance state, and research workdirs are excluded. Built with Claude Code and OpenAI Codex CLI as first-class contributors — see AGENTS.md for the agent operating contract (TDD required, AI review comments treated as hypotheses).

A personal AI companion runtime with:

• multi-interface chat (Telegram, Discord, CLI, web chat)
• scheduled/background jobs (schedule_*, subagent_*)
• memory indexing + retrieval (memory_*)
• document ingestion and conversion pipeline
• live dashboard (sessions, learning, jobs, documents, live events)

Canonical docs

Use AGENTS.md as the source of truth for architecture, contributor workflow, command surface, and operational caveats.

This README is intentionally concise to reduce doc drift.

Requirements

• Node.js 22.22.x (see .nvmrc)
• pnpm 10.28.x (via Corepack)
• Credentials for your chosen provider:
  • Anthropic: ANTHROPIC_API_KEY or Claude Code login auth
  • OpenRouter: OPENROUTER_API_KEY

Quick start (local dev)

corepack enable
corepack prepare pnpm@10.28.1 --activate
pnpm install --frozen-lockfile
pnpm build
pnpm start

On first run, doot bootstraps an instance and setup files.

Common commands

pnpm start             # main CLI/runtime (src/bin/doot.ts)
pnpm dev               # watch mode for doot entrypoint
pnpm build             # compile TS + copy dashboard assets
pnpm test              # unit tests
pnpm test:all          # unit + integration tests
pnpm check:todo        # TODO/FIXME convention check
pnpm check:complexity  # complexity baseline (eslint)
pnpm check:deadcode    # deadcode baseline (staged, non-blocking)
pnpm check:dup         # duplication baseline (staged, non-blocking)
pnpm readiness:audit   # agent-readiness baseline snapshot
pnpm readiness:debt:status   # show debt gate current-vs-target status
pnpm readiness:debt:gate     # progressive blocking quality/security gate
pnpm security:audit    # dependency audit (staged, non-blocking)
pnpm dashboard:dev     # dashboard frontend dev server
pnpm db:migrate        # dashboard DB migrations
pnpm doctor:document-pipeline

Runtime at a glance

• Entry point: src/bin/doot.ts
• Service orchestrator: src/bin/orchestrator.ts
• Dashboard backend: src/dashboard/server.ts
• Router/session orchestration: src/interfaces/router.ts
• Scheduler + background execution: src/scheduler/*
• Memory orchestration and search: src/memory/*

Child dev tool controls

For child dev runs (profile=dev), the default tool set includes: read, bash, edit, write, grep, find, ls.

You can narrow this per child/proposal with:

• tools_allow: explicit allowlist (omit/empty = default set)
• tools_deny: explicit denylist applied on top

For exact tool names, API endpoints, and behavior details, see AGENTS.md.