Your highly autonomous and incredibly curious octopus friend.

Quickstart

Bootstrap a new workspace in an empty directory (or an existing Tako workspace), then launch Tako's interactive terminal app:

mkdir tako-workspace
cd tako-workspace
curl -fsSL https://tako.bot/setup.sh | bash

# Next runs:
.venv/bin/takobot

# In app: hatchling onboarding asks name -> purpose -> XMTP handle?
# Startup: health check (instance + resources + lock)
# After onboarding: stage moves to child (world learning)
# Child chat starts with small context questions (who/where/what you do)
# Child can capture favorite websites into world_watch.sites automatically
# After pairing: XMTP adds remote control; terminal keeps full local operator control

Developer utilities: .venv/bin/takobot doctor and .venv/bin/takobot hi --to <to> [--message ...].

The three systems

• Memory system: durable knowledge in git-tracked Markdown (memory/) guided by repo-root MEMORY.md frontmatter spec.
• Emotion system: deterministic DOSE state (.tako/state/dose.json) that biases escalation sensitivity and tone.
• Productivity system: GTD + PARA execution structure (tasks/, projects/, areas/, resources/, archives/) plus open loops (.tako/state/open_loops.json).
• Life stages: hatchling → child → teen → adult with stage policies in tako.toml.
• Safety boundary: operator control + quarantine-first skill/tool installs (analyze → operator accept → install enabled).

Tako stays git-first: memory and productivity artifacts are reviewable; runtime state lives under .tako/ and is never committed.

What happens on first run

• Creates a Python virtual environment in .venv/.
• Attempts to install or upgrade the engine with pip install --upgrade takobot (PyPI, including XMTP dependency). If that fails and no engine is present, it falls back to a source clone install.
• Materializes the workspace from engine templates (takobot/templates/**) without overwriting existing files, then initializes git on main if available.
• Ships a baseline model tuning reference at resources/model-guide.md for provider/model/thinking-level calibration.
• Generates .tako/keys.json with a wallet key and DB encryption key (unencrypted; file-perms only).
• Creates the local XMTP database in .tako/xmtp-db/.
• Creates runtime logs/temp dirs at .tako/logs/ and .tako/tmp/.
• Initializes the memory system by ensuring today’s daily log exists at memory/dailies/YYYY-MM-DD.md.
• Runs a startup health check to classify environment state (brand-new vs established), verify lock/safety, and probe resources.
• Ensures required workspace-local pi runtime/auth is available, auto-syncs local Codex OAuth tokens into workspace pi auth when present, and writes inference metadata to .tako/state/inference.json.
• Loads auto-update policy from tako.toml ([updates].auto_apply, default true).
• Inference is pi-runtime-first and required; when pi is unavailable, Tako falls back to heuristic guidance instead of alternate model CLIs.
• Installs pi runtime by default under .tako/pi/node; if Node/npm are missing, bootstraps workspace-local nvm under .tako/nvm.
• Keeps npm cache local to the workspace under .tako/npm-cache when installing Node tools.
• Supports direct inference configuration from commands: provider preference (auto|pi), persisted API keys, and pi OAuth inventory.
• Supports assisted pi login in-app: inference login relays prompts and accepts operator responses via inference login answer <text>.
• Pins inference subprocess temp output and TMPDIR/TMP/TEMP to .tako/tmp/ (workspace-local only).
• Applies pi prompt guards before invocation: wraps oversized lines and trims over-budget prompts to avoid splitter chunk-limit failures.
• Keeps inference execution gated until the first interactive chat turn, so startup remains deterministic.
• Initializes the emotion system (DOSE) at .tako/state/dose.json and shows it live in the TUI.
• Uses a committed productivity system (GTD + PARA): tasks/, projects/, areas/, resources/, archives/.
• Launches the interactive terminal app and runs onboarding as explicit states (or falls back to stdout daemon mode when no interactive TTY is available).
• Uses stage policy from tako.toml ([life].stage) to control exploration cadence, Type2 budget/day, and DOSE baseline multipliers.
• Installs tako.sh with the package as a shell wrapper; deployed mode dispatches to installed takobot.
• Runs hatchling onboarding in order (name, purpose, XMTP handle), sends outbound pairing DM when applicable, and stores operator metadata in .tako/operator.json when paired.
• Offers a morning prompt to set 3 outcomes for today (stored in memory/dailies/).
• Starts a runtime service (heartbeat + exploration + sensors) with EventBus-backed Type 1 triage and Type 2 escalation for serious events.
• World Watch uses RSS/Atom feeds from tako.toml and, in child stage, randomly samples Reddit/Hacker News/Wikipedia; it writes deterministic notes (including mission-linked questions) to memory/world/, captures operator context in memory/people/operator.md, and adds operator-shared sites to [world_watch].sites.
• When runtime sits idle, boredom signals lower DOSE and trigger autonomous exploration sweeps (roughly hourly by default).
• When auto-updates are enabled, applies detected package updates and restarts the TUI automatically.
• On each heartbeat, auto-commits pending workspace changes and verifies no tracked changes remain.
• If git identity is missing, startup/heartbeat auto-configure repo-local identity from bot name (<name> <name.tako.eth@xmtp.mx>) and retry commit.
• If runtime health detects actionable problems, Tako auto-creates/reuses matching follow-up tasks under tasks/.
• Ensures a git-ignored code/ directory exists for repo clones and code-work sandboxes.
• Seeds an OpenClaw-informed starter skill pack into skills/, registers those skills, and auto-enables installed extensions.
• If required setup is missing and auto-remediation fails (for example git identity), asks the operator in-app with concrete fix steps.
• Shows an animated mind indicator in the TUI while Tako is thinking/responding.
• Uses XMTP typing indicators for outbound replies when supported by the installed XMTP SDK/runtime.
• Persists chat sessions in .tako/state/conversations/ (sessions.json + per-session JSONL transcripts) and injects recent history into inference prompts.
• Checks DOSE-derived focus on every inference and runs ragrep semantic recall over memory/ with adaptive breadth (focused: minimal context, diffuse: broader context) using runtime-local index state in .tako/state/ragrep-memory.db.
• Maintains an open-loops index at .tako/state/open_loops.json (unfinished tasks + onboarding prompts) and shows it in the sidebar.
• Shows a live activity panel (inference/tool/runtime) plus a top-right stage-specific ASCII octopus panel with Takobot version and compact DOSE indicators.

Control plane

Operator control is available in the terminal app and over the paired XMTP channel. There is no user-facing configuration via environment variables or CLI flags.

• Before pairing: terminal app is primary onboarding/control loop.
• After pairing: XMTP provides remote control for identity/config/tools/routines, while terminal keeps full local operator control.
• After pairing, operator commands include: help, status, doctor, config, task/tasks/done, morning/outcomes/compress/weekly/promote, update, web, run, reimprint.
• run command execution uses code/ as working directory (git-ignored).
• workspace.name in tako.toml is treated as Tako’s identity name and syncs with rename flows.
• Use config to get an inline explanation of current tako.toml options/values.
• doctor auto-runs inference repair first (workspace pi runtime/auth), then runs offline diagnostics (provider CLI probes + recent inference error scan) without needing inference.
• Starter skills include OpenClaw top-download capabilities, prioritized skill-creator + tool-creator + mcporter-mcp, and an agent-cli-inferencing guide that nudges toward @mariozechner/pi-ai.
• Pi chat inference runs with tools/skills/extensions enabled and can use workspace skills/ + tools/ directly.
• Workspace ships standard web tool names under tools/: web_search (discovery) and web_fetch (source extraction, optional Playwright rendering).
• Plain-text XMTP messages are treated as chat (inference-backed when available); command-style messages route to command handlers.
• Terminal remains a local cockpit for status/logs/safe mode, plain-text chat, and local operator configuration commands.
• TUI clipboard helpers: Ctrl+Shift+C copies transcript, Ctrl+Shift+L copies last line.
• TUI input supports history recall: ↑/↓ cycles previously submitted local messages.
• TUI slash shortcuts: type / to open a command dropdown under the input field, including /models, /stats, /upgrade, and /dose <channel> <0..1>.
• TUI command input supports Tab autocomplete for command names and cycles matching candidates on repeated Tab.
• Local TUI input is queued so long-running turns do not block new entry; pending input count is visible in status and sensors.
• Outbound XMTP replies are mirrored into the local TUI transcript/activity feed for a unified conversation view.
• Mission objectives are formalized in SOUL.md (## Mission Objectives) and editable in-app via mission show|set|add|clear.
• Bubble stream now shows the active request focus and elapsed thinking/responding time for long responses.
• Prompt context stack parity: local TUI and XMTP chat both include SOUL.md/SKILLS.md/TOOLS.md excerpts, live capability inventories, MEMORY.md frontmatter, focus summary, semantic RAG context, and recent conversation history.
• Child-stage chat is less interrogative: it answers first, avoids asking which channel is in use, and applies profile-aware anti-repeat guidance for follow-up questions.
• Incremental pi thinking stream chunks are coalesced into one inline thinking line (instead of newline-per-token), while structural markers stay separate.
• During streamed inference, tool/research progress is surfaced as live "active work" in the Tasks panel (for example browsing/search/tool steps).
• TUI right-click on selected transcript/stream text copies that selection in-app without clearing it.
• XMTP runtime is more resilient: transient send errors are retried and repeated poll/stream failures trigger client-session rebuilds.
• Inference stream emits periodic debug wait updates and applies a total local-chat timeout budget to avoid indefinite response stalls.
• Pi chat logs include turn summaries in .tako/logs/runtime.log and .tako/logs/app.log (pi chat user/pi chat assistant).
• Even unexpected provider exceptions (outside normal subprocess exits) are appended to .tako/logs/error.log with traceback context.
• Local/XMTP chat prompts enforce canonical identity naming from workspace config/identity state after rename updates.
• Runtime state lives under .tako/ and is never committed.

Note: treat .tako/keys.json as sensitive (and never commit anything under .tako/).

Operational notes

• XMTP requires outbound network access; if messaging fails, double-check your HTTPS / HTTP2 egress.
• Runtime cognition consumes .tako/state/events.jsonl with Type 1 triage and escalates critical signals to Type 2 depth tasks.
• Type 2 uses the required pi runtime for model reasoning; if pi is unavailable/fails, Tako falls back to heuristic safety recommendations.
• Before the first interactive turn, Type 2 remains heuristic-only by design.
• The daemon retries XMTP stream subscriptions with backoff and falls back to polling when stream errors persist.
• XMTP client initialization disables history sync by default for compatibility.
• Workspace bootstrap is venv + pip. No uv required.
• If you see DB errors (e.g., “file is not a database”), delete .tako/xmtp-db (or delete .tako/) to force a clean rebuild.
• ENS resolution tries configured RPC endpoints first and may fall back to a public resolver if needed.

Links

• GitHub: github.com/pierce403/takobot
• Docs: AGENTS, SOUL, VISION, MEMORY, SKILLS, TOOLS, ONBOARDING
• Features: FEATURES.md
• Entrypoint: setup.sh then .venv/bin/takobot
• CLI: .venv/bin/takobot or python -m takobot

Want this page hosted? Enable GitHub Pages and point it at the branch/folder that contains index.html.