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). 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 (including local tako.sh launcher materialization), 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 and XMTP CLI runtime under .tako/xmtp/node; if Node/npm are missing or system Node is below runtime requirements (<22), 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, pi OAuth inventory, and Type1/Type2 model lane overrides via models set type1|type2 <model|auto>.
• Operator plain-text chat can also save or clear runtime-local OpenAI/Venice inference keys directly (for example set my openai api key to ..., clear my venice api key) without dropping into command syntax.
• Supports assisted pi login in-app only when the installed pi CLI exposes a supported login/auth login command. Otherwise Tako reports manual auth or API-key recovery guidance instead of attempting unsupported subcommands. inference login force still forces a fresh re-auth when assisted login is supported.
• Workspace pi auth sync refreshes from newer local ~/.pi auth profiles and does not overwrite an existing workspace openai-codex OAuth entry with Codex-imported tokens.
• When inference fails with OpenAI refresh-token errors, fallback replies include non-inference recovery steps (inference login force, inference login answer <text>, inference refresh, inference auth), and XMTP chat attempts auto-repair first.
• 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).
• If terminal capability is too limited for Textual UI (TERM=dumb|unknown, missing TERM, or non-TTY stdin/stdout), takobot app falls back automatically to simple text-only runtime logs (takobot run).
• 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.
• If pi stream mode fails (for example unsupported stream-json or thinking flags), inference now auto-falls back to sync pi execution instead of failing the turn immediately.
• Pi inference subprocesses are forced non-interactive (stdin=DEVNULL, CI=1), and interactive prompts (for example Press any key to continue...) now fail fast instead of hanging until timeout.
• Pi sync retry now preserves --print --mode text --no-session for model-thinking fallback (minimal->low, xhigh->high) and only drops optional flags for true unknown-option compatibility retries.
• Type1 local/XMTP chat now defaults to fast openai/gpt-5.1-codex-mini (unless overridden with models set type1 ...), while Type2 keeps deep model selection from base/override settings.
• Pi capability sync now remediates deprecated legacy tools/ mappings into extensions/ locations (global agent + project .pi/) so migration prompts do not block inference.
• Name-intent inference checks now run only when messages hint at rename/profile changes and use a short timeout, so normal smalltalk does not trigger extra rename-classifier calls.
• Operator requests to set/sync XMTP display name/profile without an explicit replacement name now trigger a direct profile-sync attempt to current identity instead of generic model chat fallback.
• Local/XMTP transcript and conversation-history storage redact API key values from both inference key set ... commands and plain-text key update requests.
• Prompt history compacts verbose inference-unavailable fallback diagnostics into a short marker line to prevent repeated fallback copy from bloating later prompts.
• Uses XMTP typing indicators for outbound replies when supported by the installed XMTP SDK/runtime.
• When paired, startup sends the operator a XMTP "back online" ping with a quick status snapshot (version/stage/inference/XMTP profile/jobs/tasks/address), including a Converge 1:1 profile confirmation line (converge.cv/profile:1.0 name/avatar sync state).
• On XMTP startup/rebuild/pairing/name updates, Tako runs profile sync through workspace-managed XMTP runtime: Converge DM metadata for 1:1 chats (converge.cv/profile:1.0) and Convos-compatible group profile upserts in appData (protobuf ConversationCustomMetadata) via a runtime Node helper; deterministic avatar/cache files are written at .tako/state/xmtp-avatar.svg, .tako/state/xmtp-profile.json, and .tako/state/xmtp-profile-broadcast.json.
• 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, jobs, task/tasks/done, morning/outcomes/compress/weekly/promote, update, web, run, exec, reimprint.
• jobs supports natural-language schedules (for example every day at 3pm run doctor) and persists schedules under .tako/state/cron/jobs.json.
• When `update` is applied over XMTP in paired TUI mode, Tako requests terminal restart automatically after sending the update result.
• run/exec command execution uses workspace root as working directory, and prepends workspace-local pi runtime bins to PATH when available.
• workspace.name in tako.toml is treated as Tako’s identity name and syncs with rename flows.
• Identity rename handling is inference-classified instead of phrase-gated; if no replacement name is provided, Tako asks for the exact target name.
• 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 uses workspace skills/ plus extensions/ (legacy tools/ fallback) in pi runtime context.
• 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 quit shortcuts: Ctrl+Q always exits app mode; Ctrl+C also exits when not running inside GNU screen.
• 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 (plan + list + set Type1/Type2), /jobs, /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 expanded local-chat timeout budgets (180s provider window, 420s total) to avoid premature timeout 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.