takobot

Tako is your highly autonomous octopus friend built in Python with a docs-first memory system and Type 1 / Type 2 thinking. By default, Tako is intentionally curious about the world and pushes toward evidence-backed answers. The direction is informed by modern productivity research and stays web3-native via XMTP and Ethereum (with Farcaster support planned). Today, this repo includes:

• A first-class interactive terminal app main loop (takobot) with transcript, status bar, panels, and input box
• If terminal capabilities are limited (TERM=dumb|unknown, missing TERM, or non-TTY stdin/stdout), takobot app now auto-falls back to simple text-only runtime logs (takobot run) instead of crashing or hanging the TUI.
• Installed shell wrapper support: tako.sh is packaged for deployments and fresh workspaces now materialize a local tako.sh launcher (dispatching to installed takobot outside repo mode)
• Startup health checks (instance shape, lock, resource probes) before entering the main loop
• Pi-first/required inference discovery: Takobot installs and uses workspace-local pi runtime (@mariozechner/pi-ai + @mariozechner/pi-coding-agent) and records key-source detection
• Pi auth bridging: when available, Takobot adopts local-system API keys (environment and common CLI auth files) for pi runtime usage
• Assisted pi login workflow: inference login relays prompts only when the installed pi CLI exposes a supported login/auth login command; otherwise Takobot reports manual auth/API-key recovery guidance. inference login force can still re-auth when assisted login is supported, and startup auto-syncs Codex OAuth from ~/.codex/auth.json into .tako/pi/agent/auth.json
• Workspace pi auth sync now refreshes from newer local ~/.pi auth profiles and no longer overwrites an existing workspace openai-codex OAuth entry with Codex-imported tokens.
• Pi chat inference keeps tools/skills/extensions enabled and links workspace skills/ plus extensions/ (with legacy tools/ fallback mapping) into the pi agent runtime context
• Pi chat turn summaries are now written to logs (.tako/logs/runtime.log and .tako/logs/app.log) so operator prompts/replies are traceable during long runs
• Inference command-level failures now log invoked command + output tails to .tako/logs/error.log
• Inference fallback replies now detect OpenAI refresh-token failures and provide non-inference reauth steps (inference login force, inference login answer <text>, inference refresh, inference auth), and XMTP chat paths attempt automatic inference runtime repair before fallback.
• Operator plain-text chat can now save or clear runtime-local OpenAI/Venice API keys directly (for example set my openai api key to ..., clear my venice api key), and stored transcript/history lines redact the secret value.
• Name-intent inference checks now run only when messages hint at rename/profile changes (for example name, rename, display name, xmtp profile) and use a short timeout, so smalltalk does not trigger extra classifier calls.
• Explicit XMTP profile requests without a replacement name (for example can you set your display name on XMTP yet?) now trigger an immediate profile-sync attempt to current identity instead of falling through to generic model chat.
• Prompt history context now compacts verbose inference-unavailable fallback diagnostics into a short marker line to avoid repeated fallback copy bloating later inference prompts.
• Pi stream inference now auto-falls back to sync pi execution when stream-json invocation fails (for example older CLI flag/value incompatibilities)
• Pi inference subprocesses are forced non-interactive (stdin=DEVNULL, CI=1), and interactive prompts like Press any key to continue... are detected as fast-fail errors instead of hanging until timeout.
• Pi sync retry logic now preserves --print --mode text --no-session for model-level thinking fallback (minimal -> low, xhigh -> high), only dropping optional flags for true unknown-option CLI compatibility retries.
• Pi capability sync now remediates deprecated legacy tools/ mappings into extensions/ locations (global + project .pi/) so migration warnings do not block inference.
• Default Node tooling install in workspace (.tako/pi/node + .tako/xmtp/node), with local nvm bootstrap under .tako/nvm when host Node/npm are missing or Node is incompatible (<22)
• Inference execution gate so first model call starts on the first interactive chat turn
• OpenClaw-style conversation management: per-session JSONL transcripts under .tako/state/conversations/ with bounded history windows injected into prompts
• A background XMTP runtime with stream retries + polling fallback
• When paired, startup sends an operator XMTP "back online" ping with a quick state summary (version/stage/inference/XMTP-profile/jobs/tasks/address), including a Converge profile confirmation line for converge.cv/profile:1.0 name/avatar sync status
• XMTP profile sync: on startup/pair/rebuild/name-change, Takobot uses a runtime Node helper (via @xmtp/node-sdk) to publish Converge 1:1 profile metadata (converge.cv/profile:1.0) and upsert Convos group appData profile metadata (ConversationCustomMetadata.profiles), generates a deterministic avatar at .tako/state/xmtp-avatar.svg, and records sync/broadcast state in .tako/state/xmtp-profile.json and .tako/state/xmtp-profile-broadcast.json
• EventBus-driven cognition: in-memory event fanout + JSONL audit + Type 1 triage + Type 2 escalation
• World Watch sensor loop: RSS/Atom polling plus child-stage curiosity crawling (Reddit/Hacker News/Wikipedia), deterministic world notebook writes, and bounded briefings
• Boredom/autonomy loop: when runtime stays idle, DOSE indicators drift down and Tako triggers boredom-driven exploration (about hourly by default) to find novel signals
• Child-stage chat tone is relationship-first: it asks one small context question at a time (who/where/what the operator does) and avoids forcing task frameworks unless asked
• Child-stage chat avoids interrogation loops: answers first, avoids asking which channel is in use, and uses profile-aware anti-repeat guidance so follow-up questions feel natural
• Child-stage operator context is captured into memory/people/operator.md; shared websites are added to [world_watch].sites in tako.toml for monitoring
• Heartbeat-time git hygiene: if workspace changes are pending, Tako stages (git add -A) and commits automatically, and verifies the repo is clean after commit
• Missing-setup prompts: when required config/deps are missing and auto-remediation fails, Tako asks the operator with concrete fix steps
• Runtime problem capture: detected warnings/errors are converted into committed tasks/ items for follow-up
• Animated "mind" indicator in the TUI (status/sidebar/stream/octopus panel) while Tako is thinking or responding
• Auto-update setting (tako.toml → [updates].auto_apply = true by default) with in-app apply + self-restart when a new package release is detected
• XMTP control-channel handling with command router (help, status, doctor, config, jobs, task, tasks, done, morning, outcomes, compress, weekly, promote, update, web, run, exec, reimprint) plus plain-text chat replies
• XMTP update now requests a terminal-app restart automatically when updates are applied in a paired TUI-hosted runtime (daemon-only mode still reports manual restart guidance)
• Natural-language scheduling for recurring jobs (every day at 3pm ...) with persisted job state at .tako/state/cron/jobs.json
• Built-in operator tools for webpage reads (web <url>) and local shell commands (run <command> or exec <command>), plus standard autonomous web tools in tools/: web_search and web_fetch
• Code work isolation: workspace includes a git-ignored code/ directory for repo clones and sandboxes, while run/exec execute from workspace root by default
• Built-in starter skills are auto-seeded into skills/ and auto-enabled: OpenClaw top skills, skill-creator, tool-creator, MCP-focused mcporter-mcp, and an agent-cli-inferencing guide that nudges toward @mariozechner/pi-ai
• TUI activity feed (inference/tool/runtime events), clipboard copy actions, and a stage-specific ASCII octopus panel with Takobot version + DOSE indicators
• Research visibility: during streamed inference, inferred tool steps (for example web browsing/search/tool calls) are surfaced as live "active work" in the Tasks panel
• TUI input history recall: press ↑ / ↓ in the input box to cycle previously submitted local messages
• TUI quit shortcuts: Ctrl+Q always exits app mode; Ctrl+C remains available when not running under GNU screen
• Slash-command UX in the TUI: typing / opens a dropdown under the input field with command shortcuts; includes /models for Type1/Type2 model plan + model-option listing + lane overrides, /jobs for schedule control, /upgrade as update alias, /stats for runtime counters, and /dose ... for direct DOSE level tuning
• TUI command entry supports Tab autocomplete for command names (with candidate cycling on repeated Tab)
• Local TUI input is now queued: long-running turns no longer block new message entry, and pending input count is shown in status/sensors
• XMTP outbound replies are mirrored into the local TUI transcript/activity feed so remote conversations stay visible in one place
• Mission objectives are formalized in SOUL.md (## Mission Objectives) and editable in-app via mission commands (mission show|set|add|clear)
• Runtime writes deterministic world notes under memory/world/YYYY-MM-DD.md and daily mission snapshots under memory/world/mission-review/YYYY-MM-DD.md
• Focus-aware memory recall on every inference: DOSE emotional state drives how much semantic RAG context is pulled from memory/ via ragrep (minimal context when focused, broader context when diffuse)
• Prompt context stack parity across channels: local TUI chat and XMTP chat now both include SOUL.md/SKILLS.md/TOOLS.md excerpts, live skills/tools inventories, MEMORY.md frontmatter, focus summary, semantic RAG context, and recent conversation history
• Effective defaults are split by cognition lane: Type1 uses fast minimal thinking with a fast coding model default (openai/gpt-5.1-codex-mini unless overridden), Type2 uses deep xhigh thinking and follows base/override model settings
• Life-stage model (hatchling, child, teen, adult) persisted in tako.toml with stage policies for routines/cadence/budgets
• Bubble stream now shows the active request focus + elapsed time while thinking/responding so long responses stay transparent
• Incremental pi thinking stream chunks now render inline in one evolving status line (instead of newline-per-token); structural markers stay on separate lines
• Inference debug telemetry is now more verbose by default (ready-provider list, periodic waiting updates, app-log traces) with expanded local-chat timeout budgets (180s provider window, 420s total) to avoid premature timeout fallback on slow turns
• TUI right-click on selected transcript/stream text now triggers in-app copy-to-clipboard without clearing the selection
• XMTP daemon resilience: retries transient send failures and auto-rebuilds XMTP client sessions after repeated stream/poll failures
• Local/XMTP chat prompts now enforce canonical identity naming from workspace/identity state, so self-introductions stay consistent after renames
• Productivity engine v1: GTD + PARA folders (tasks/, projects/, areas/, resources/, archives/), daily outcomes, weekly review, progressive summaries
• Docs-first repo contract (SOUL.md, VISION.md, MEMORY.md, SKILLS.md, TOOLS.md, ONBOARDING.md)
• OpenClaw-style docs tree in docs/ (start/, concepts/, reference/)

Docs

• Website: https://tako.bot (or index.html in this repo)
• Docs directory: docs/ (OpenClaw-style start/, concepts/, reference/)
• Features: FEATURES.md
• Agent notes / lessons learned: AGENTS.md

Quickstart

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

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

If no interactive TTY is available, bootstrap falls back to command-line daemon mode (python -m takobot run) instead of exiting.

Next runs:

.venv/bin/takobot

Bootstrap refuses to run in a non-empty directory unless it already looks like a Tako workspace (has SOUL.md, AGENTS.md, MEMORY.md, tako.toml).

Pairing flow:

• takobot always starts the interactive terminal app first.
• During hatchling onboarding, Tako asks in this order:
  • name
  • purpose
  • XMTP handle yes/no (pair now or continue local-only)
• Identity naming accepts freeform input and uses inference to extract a clean name (for example, “your name can be SILLYTAKO”).
• Rename handling in running chat is inference-classified (not phrase-gated): if you request a rename without giving the target name, Tako asks for the exact replacement.
• After pairing, XMTP adds remote operator control for identity/config/tools/routines (help, status, doctor, config, jobs, task, tasks, done, morning, outcomes, compress, weekly, promote, update, web, run, exec, reimprint) while the terminal keeps full local operator control.

Productivity (GTD + PARA):

• morning sets today’s 3 outcomes (stored in memory/dailies/YYYY-MM-DD.md).
• task <title> creates a committed task file under tasks/.
• tasks lists open tasks (filters: project, area, due).
• done <task-id> completes a task.
• compress writes a progressive summary block into today’s daily log.
• weekly runs a weekly review report.
• promote <note> appends an operator-approved durable note into MEMORY.md.
• jobs add <natural schedule> (or plain language like every day at 3pm explore ai news) schedules recurring actions.

Architecture (minimal)

Committed (git-tracked):

• SOUL.md, MEMORY.md, SKILLS.md, TOOLS.md, ONBOARDING.md, AGENTS.md, tako.toml
• FEATURES.md (feature tracker)
• memory/dailies/YYYY-MM-DD.md (daily logs)
• memory/world/ (YYYY-MM-DD.md, model.md, entities.md, assumptions.md)
• memory/reflections/, memory/contradictions/ (reflection + contradiction tracking)
• tasks/, projects/, areas/, resources/, archives/ (execution structure)
• tools/ (workspace tools; operator-approved installs are auto-enabled)
• skills/ (workspace skills; starter pack + operator-approved installs are auto-enabled)

Runtime-only (ignored):

• .tako/keys.json (XMTP wallet key + DB encryption key; unencrypted, file perms only)
• .tako/operator.json (operator imprint metadata)
• .tako/logs/ (runtime and terminal logs)
• .tako/tmp/ (workspace-local temp files used by inference and bootstrap fallback)
• .tako/nvm/ (workspace-local Node runtime via nvm when system Node is unavailable)
• .tako/npm-cache/ (workspace-local npm cache for tool installs)
• .tako/xmtp-db/ (local XMTP DB)
• .tako/state/** (runtime state: heartbeat/cognition/etc)
• .tako/quarantine/** (download quarantine for skills/tools)
• .venv/ (local virtualenv with the engine installed)

What happens on first run

• Creates a local 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 clones source into .tako/tmp/src/ and installs from there.
• Installs local pi runtime in .tako/pi/node (@mariozechner/pi-ai + @mariozechner/pi-coding-agent) by default; if Node/npm are missing or Node is below the managed runtime baseline (>=22), bootstrap installs workspace-local nvm + Node under .tako/nvm first.
• Installs local XMTP CLI runtime in .tako/xmtp/node (@xmtp/cli@0.2.0) using the same managed Node baseline and npm cache.
• Materializes the workspace from engine templates (takobot/templates/**) without overwriting existing files (including workspace tako.sh launcher materialization).
• Seeds a baseline model tuning guide at resources/model-guide.md.
• Initializes git (if available) and commits the initial workspace.
• If initial git commit is blocked by missing identity, bootstrap sets repo-local fallback identity from workspace.name (email format: <name>.tako.eth@xmtp.mx) and retries.
• Ensures a git-ignored code/ directory exists for temporary repo clones/code work.
• Generates a local key file at .tako/keys.json with a wallet key and DB encryption key (unencrypted; protected by file permissions).
• Creates runtime logs/temp directories at .tako/logs/ and .tako/tmp/.
• Creates a local XMTP database at .tako/xmtp-db/.
• Launches the interactive terminal app main loop (takobot, default).
• Runs a startup health check to classify instance context (brand-new vs established), verify lock/safety, and inspect local resources.
• If required setup is missing, emits an in-app operator request with direct remediation steps.
• Detects pi runtime/auth/key sources (including Codex OAuth import into .tako/pi/agent/auth.json when available) and persists runtime metadata to .tako/state/inference.json.
• If workspace-local pi runtime is missing, runtime discovery bootstraps workspace-local nvm/node and installs pi tooling under .tako/.
• Loads auto-update policy from tako.toml ([updates].auto_apply, default true).
• Runs stage-aware onboarding as an explicit state machine inside the app (name -> purpose -> XMTP handle).
• Shows an activity panel in the TUI so you can see inference/tool/runtime actions as they happen.
• Shows the top-right octopus panel with Takobot version and compact DOSE indicators (D/O/S/E).
• Starts the runtime service (heartbeat + exploration + sensors) and continuously applies Type 1 triage; serious events trigger Type 2 tasks with depth-based handling.
• Type 2 escalation uses the required pi runtime after the first interactive turn; if pi is unavailable/fails, Type 2 falls back to heuristic guidance.
• Seeds starter skills into skills/, registers them, and auto-enables installed extensions.
• If paired, starts background XMTP runtime and keeps terminal as local cockpit with plain-text chat still available.

Configuration

There is no user-facing configuration via environment variables or CLI flags.

Workspace configuration lives in tako.toml (no secrets).

• workspace.name is the bot’s identity name and is kept in sync with rename/identity updates.
• Auto-update policy lives in [updates] (auto_apply = true by default). In the TUI: update auto status|on|off.
• World-watch feeds live in [world_watch] (feeds = [...], poll_minutes = <minutes>).
• Website watch-list lives in [world_watch].sites and is automatically updated when child-stage chat captures operator-preferred websites.
• In child stage, world-watch also performs random curiosity sampling from Reddit, Hacker News, and Wikipedia.
• Use config (local TUI) or XMTP config to get a guided explanation of all tako.toml options and current values.
• Inference auth/provider settings are runtime-local in .tako/state/inference-settings.json and can be managed directly with inference ... commands (provider preference auto|pi, API keys, pi OAuth inventory).
• Operator plain chat can also set or clear runtime-local OpenAI/Venice inference keys without command syntax; Takobot redacts the raw key from transcript/history storage.
• doctor runs local/offline inference diagnostics (CLI probes + recent inference error scan), attempts automatic workspace-local inference repair first, and does not depend on inference being available.
• Extension downloads are always HTTPS; non-HTTPS is not allowed.
• Security permission defaults for enabled extensions are now permissive by default (network/shell/xmtp/filesystem = true), and can be tightened in tako.toml.

Any change that affects identity/config/tools/sensors/routines must be initiated by the operator (terminal app or paired XMTP). Natural-language operator requests can be applied directly, and durable changes should still be reflected in repo-tracked docs (SOUL.md, MEMORY.md, etc).

Developer utilities (optional)

• Local checks: .venv/bin/takobot doctor
• One-off DM send: .venv/bin/takobot hi --to <xmtp_address_or_ens> [--message ...]
• Direct daemon (dev): .venv/bin/takobot run
• Test suite: .venv/bin/python -m unittest discover -s tests -p 'test_*.py'
• Feature checklist guard: tests/test_features_contract.py parses every FEATURES.md test criterion and enforces probe coverage so checklist drift is caught in CI/local runs.
• Research-note scenario: tests/test_research_workflow.py validates that a research topic can fetch sources and write structured daily notes.

Notes

• Workspaces are git-first, but git is optional. If git is missing, Tako runs and warns that versioning is disabled.
• The daemon now retries XMTP stream subscriptions with backoff when transient group/identity stream errors occur.
• When stream instability persists, the daemon falls back to polling message history and retries stream mode after polling stabilizes.
• While running, Tako periodically checks for package updates. With updates.auto_apply = true, the TUI applies the update and restarts itself.
• XMTP transport runs through workspace-managed @xmtp/cli with local DB at .tako/xmtp-db/xmtp-production.db3.
• Runtime event log lives at .tako/state/events.jsonl as an audit stream; events are consumed in-memory via EventBus (no JSONL polling queue).
• World Watch sensor state is stored in .tako/state/rss_seen.json and .tako/state/curiosity_seen.json; briefing cadence/state is stored in .tako/state/briefing_state.json.
• Runtime inference metadata lives at .tako/state/inference.json (no raw secrets written by Tako).
• Runtime daemon logs are appended to .tako/logs/runtime.log; TUI transcript/system logs are appended to .tako/logs/app.log.
• Pi-backed chat adds explicit pi chat user / pi chat assistant summary lines in runtime/app logs.
• Inference now runs through workspace-local pi runtime; if pi is not available, Takobot falls back to non-inference heuristic responses.
• Inference subprocess temp output and TMPDIR/TMP/TEMP are pinned to .tako/tmp/ (workspace-local only).
• Chat context is persisted in .tako/state/conversations/ (sessions.json + per-session JSONL transcripts) and recent turns are injected into prompt context.
• On each heartbeat, Tako checks git status and auto-commits pending workspace changes (git add -A + git commit) when possible.
• Scheduled jobs are evaluated on heartbeat ticks (default cadence: every 30s in app mode), then queued as local actions when due.
• If git auto-commit encounters missing git identity, Tako auto-configures repo-local identity from the bot name (<name> <name.tako.eth@xmtp.mx>) and retries the commit.
• When runtime/doctor detects actionable problems (git/inference/dependency/runtime), Tako opens/maintains matching tasks under tasks/ automatically.
• The bootstrap launcher rebinds stdin to /dev/tty for app mode, so curl ... | bash can still start an interactive TUI.
• XMTP replies now use a typing indicator when supported by the installed XMTP SDK/runtime.
• Transcript view is now selectable (read-only text area), so mouse highlight/copy works directly in compatible terminals.
• Input box supports shell-style history recall (↑ / ↓) for previously submitted local messages.
• Web reads are fetched with the built-in web tool and logged into the daily notes stream for traceability.
• Semantic memory recall uses ragrep when installed (ragrep CLI); index state is runtime-only at .tako/state/ragrep-memory.db.
• XMTP transport is runtime-managed via npm (@xmtp/cli@0.2.0 under .tako/xmtp/node); if runtime health reports XMTP unavailable, run doctor and ensure Node >=22 is available (system or .tako/nvm).