{"id":47953579,"url":"https://github.com/asermax/tachikoma","last_synced_at":"2026-06-16T05:01:13.342Z","repository":{"id":348185973,"uuid":"1175782315","full_name":"asermax/tachikoma","owner":"asermax","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-06T02:23:35.000Z","size":7302,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-06T04:22:45.857Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asermax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T06:46:34.000Z","updated_at":"2026-06-06T02:23:38.000Z","dependencies_parsed_at":"2026-04-08T06:01:00.143Z","dependency_job_id":null,"html_url":"https://github.com/asermax/tachikoma","commit_stats":null,"previous_names":["asermax/tachikoma"],"tags_count":138,"template":false,"template_full_name":null,"purl":"pkg:github/asermax/tachikoma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asermax%2Ftachikoma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asermax%2Ftachikoma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asermax%2Ftachikoma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asermax%2Ftachikoma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asermax","download_url":"https://codeload.github.com/asermax/tachikoma/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asermax%2Ftachikoma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34271500,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T09:21:45.490Z","updated_at":"2026-06-13T04:01:17.404Z","avatar_url":"https://github.com/asermax.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tachikoma\n\nTachikoma is a proactive personal assistant built on the [pi agent SDK](https://github.com/earendil-works/pi). It maintains persistent memory across conversations, extracts learnings automatically, handles background tasks during idle time, and is reachable through Telegram or a local REPL.\n\nThe core is deliberately thin — config, database, scheduler, channels, session orchestration, and an extension host — and **every feature is an extension**: memory, conversation boundary detection, skills, workflows, scheduled tasks, project tracking, git-versioned workspace, Telegram, detached process supervision, notifications, and external extension loading (out-of-tree extensions on the same contract, installable from git).\n\n## Install\n\n```bash\nnpm i -g @asermax/tachikoma\ntachikoma           # start the agent (REPL channel)\ntachikoma -c telegram\n```\n\nReleases are published automatically: `just release` bumps the version and tags via commit-and-tag-version, then `git push --follow-tags` triggers the publish workflow. Maintainers must configure an `NPM_TOKEN` repository secret with publish access to the `@asermax` scope.\n\n## Requirements\n\n- Node.js \u003e= 22.19 (the project runs TypeScript sources directly via native type stripping)\n- pnpm\n- LLM provider credentials: an existing [pi](https://pi.dev) login (`~/.pi/agent/auth.json`) is picked up automatically, or set a provider key like `ANTHROPIC_API_KEY` in the environment\n\n## Quick start\n\n```bash\njust install            # pnpm install\njust run                # start the agent (REPL channel)\njust run -c telegram    # start with the Telegram channel\n```\n\nOn first run a commented config file is generated at `~/.config/tachikoma/config.toml` and the workspace at `~/tachikoma` is initialized (SOUL.md, USER.md, memory layout, git repo).\n\n## Configuration\n\nTOML at `~/.config/tachikoma/config.toml`. Core sections: `[workspace]`, `[agent]` (optional per-role models as `provider/model-id[:thinkingLevel]` — anything unset defers to pi), `[logging]`, `[channels]`, `[sessions]`, `[scheduler]`. pi-level knobs (default model, thinking budgets, compaction, retry, custom providers) live in pi's own `settings.json`/`models.json` under `{workspace}/.tachikoma/pi/`. Each extension reads its own `[extensions.\u003cname\u003e]` section — see the generated file and the feature specs in `docs/feature-specs/`.\n\n## Development\n\n```bash\njust check       # lint + typecheck + tests (run before considering anything done)\njust test        # vitest\njust lint        # biome check\njust fmt         # biome check --write\njust typecheck   # tsc --noEmit\n```\n\nDatabase migrations: schema lives in `src/db/schema.ts` (aggregating per-extension `schema.ts` modules); generate migrations with `pnpm drizzle-kit generate` — they apply automatically at startup.\n\n## Architecture\n\n```\nChannel (telegram/repl extension)\n  → Coordinator (core): inbound middleware → session ensure/resume\n    → context providers (parallel) → pi AgentSession prompt\n    → AgentEvents streamed back to the channel\n  → exchange processors (rolling summary, …)\n  → on idle close: post-processing phases (memory extraction, git commit, …)\n```\n\n- **Extensions** implement features through one contract (`defineExtension`) with app-level hooks (scheduler, db, sessions, channels) and pi-native session hooks (`app.agent.use((pi) =\u003e …)`). Start at `docs/design/DES-001-unified-extension-api.md` and `DES-002-extension-authoring.md`.\n- **pi SDK ground truth** for this codebase: `docs/reference/pi-sdk-notes.md`.\n- **Planning docs**: `docs/planning/VISION.md`, `docs/planning/DELTAS.md`; decisions in `docs/architecture/ADR-*`; feature documentation under `docs/feature-specs/` and `docs/feature-designs/`.\n\nThe agent's pi state (sessions, settings) lives isolated under `{workspace}/.tachikoma/pi`, so it never interferes with a personal pi installation; provider credentials are shared from the machine-level pi login when present.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasermax%2Ftachikoma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasermax%2Ftachikoma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasermax%2Ftachikoma/lists"}