{"id":50666652,"url":"https://github.com/decocms/tama","last_synced_at":"2026-06-08T07:03:30.285Z","repository":{"id":361953789,"uuid":"1256591029","full_name":"decocms/tama","owner":"decocms","description":"An agent for your pet to live a better life. Fork it, adopt it for your pet, deploy to your own Cloudflare. One pet, one agent, one deploy.","archived":false,"fork":false,"pushed_at":"2026-06-01T23:57:12.000Z","size":564,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T01:21:20.410Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decocms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T23:27:29.000Z","updated_at":"2026-06-01T23:57:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/decocms/tama","commit_stats":null,"previous_names":["decocms/tama"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/decocms/tama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Ftama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Ftama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Ftama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Ftama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decocms","download_url":"https://codeload.github.com/decocms/tama/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Ftama/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34051772,"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-08T02:00:07.615Z","response_time":111,"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-06-08T07:02:57.336Z","updated_at":"2026-06-08T07:03:30.279Z","avatar_url":"https://github.com/decocms.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tama\n\nAn agent for your pet to live a better life. One pet, one agent, one deploy.\n\nThis repo is a **template**. You fork it, ask a coding-agent (Studio,\nClaude Code, …) to set it up for *your* pet — creating an agent that knows\nyour pet — and deploy it to your own Cloudflare account. The deployed worker\nis that agent: dashboard at `/`,\nan ambient pixel companion at `/companion`, MCP server at `/mcp`. Free, MIT,\nyour data lives in your account — we never see it.\n\n→ Landing: \u003chttps://tama.vet\u003e\n→ Live demo: \u003chttps://tama-example.deco-ceo.workers.dev\u003e (Pixel, an anemia-recovery case)\n\n## What you get\n\n- **Medical log** — upload exams (PDF or photo); Claude vision extracts every\n  parameter, maps each to a canonical taxonomy (so \"TGP\" and \"ALT\" land in\n  the same bucket), and charts evolution over time. Prescription photos\n  become a live timetable with dose logging and push reminders.\n- **An agent for your pet** — `/mcp` exposes the whole surface as MCP tools.\n  Studio imports it and chat becomes admin: \"Did I give Beto his Prelone?\"\n  \"What was his hemoglobin trend?\" \"Look up Sucralfate side effects.\"\n- **A pixel companion** — `/companion` is a tiny pixel face that lives on your\n  home screen (PWA). Generated from a photo by a single Claude vision call that\n  reads the photo into a character sheet (coat colors, ear shape, markings),\n  then a deterministic SVG renderer draws 6 emotion variants (idle, happy,\n  hungry, pill-time, sad, sleeping) — instant, free, crisp at any size. Reacts\n  ambient to the dose schedule.\n\n## How to create your pet's agent\n\n**You need two things: a coding agent ([Claude Code](https://claude.com/claude-code))\nand a GitHub account.** Studio handles the rest — you don't write code, you have\na conversation.\n\n**The guided path — [deco studio](https://studio.decocms.com):** connect your\nGitHub, point Studio at this repo, and Studio runs the project like a coding\nagent does — it has git, a shell, and Claude right there in the chat. It reads\n[`AGENTS.md`](./AGENTS.md) and walks you through it: it asks a few questions\nabout your pet, forks and customizes the code for you, draws the pixel sprite,\nand deploys to *your* own Cloudflare account. No terminal, no copy-pasting\ncommands — just answer questions and approve the deploy. Studio takes you the\nwhole way.\n\n**On your own machine:** open your fork in Claude Code and run the\n[`/create-agent`](./.claude/skills/create-agent.md) skill — the same `AGENTS.md`\nflow, in your editor. Cursor, Aider, or doing it by hand from\n[`AGENTS.md`](./AGENTS.md) all work too; every step is a real shell command.\n\n## Architecture\n\n- **Cloudflare Worker** (`api/main.cf.ts`) — MCP server, REST endpoints,\n  cron-driven push notifications, static asset serving.\n- **D1** (`api/db/schema.ts`) — singleton `pets` row + notes / prescriptions /\n  doses / schedule_state / recordings / exams / metrics / vet_visits /\n  vaccines / symptoms. Accessed via Drizzle ORM.\n- **R2** — uploaded files (the Assets library: exam PDFs, vaccine cards,\n  audio chunks, per-pet sprite pack).\n- **Cloudflare AI Gateway** — routes Anthropic (vision extraction, exam\n  parsing, asset classification, character sheet) and Perplexity (vet\n  research). No API keys live in the Worker; the gateway holds BYOK.\n- **Workers AI** — Whisper transcription for audio recordings. (The companion\n  sprite is procedural SVG — no image model, instant + free.)\n- **React UI** (`web/`) — bundled to a single HTML by Vite. Three top-level\n  apps (Pet / Timeline / Timetable) + exams, companion, and sprite-lab, all\n  served from the same Worker.\n\nThe repo is single-pet by design — there are no episodes; every record hangs\noff the singleton `pet_self` and the **timeline** is a query-time merge across\nthe typed tables. No multi-tenant plumbing, no pet picker, no \"which pet\"\nquestion to ever ask.\n\nTo explore with realistic data: `bun run seed:example` loads a synthetic\nexample pet (\"Pixel\", an anemia-recovery case). To pull template updates into\na fork: `bun run update` (see [docs/UPDATING.md](./docs/UPDATING.md)).\n\n## Local development\n\nAfter setting up the agent for your pet:\n\n```bash\nbun install\nbun run db:migrate:local\nbun run dev\n```\n\n`vite build --watch` rebuilds the UI; `wrangler dev` serves the worker\nat `http://localhost:8787`. Miniflare emulates D1 + R2 with persistence.\n\n## Deploy\n\n```bash\n# Provision (once)\nwrangler d1 create tama-\u003cpetslug\u003e          # patch wrangler.toml database_id\nwrangler r2 bucket create tama-\u003cpetslug\u003e-files\n\n# Secrets (once)\nbun run scripts/generate-vapid.ts          # generate VAPID keypair\nwrangler secret put VAPID_PUBLIC_KEY\nwrangler secret put VAPID_PRIVATE_KEY\nwrangler secret put VAPID_SUBJECT          # mailto:you@example.com\nwrangler secret put ANTHROPIC_API_KEY\n\n# Deploy (every time)\nbun run db:migrate:remote\nbun run deploy\n```\n\n## Migrating from the legacy `myvet` shape\n\nIf you ran the pre-tama (episode-era) version on a Cloudflare account and\nwant to bring one pet's data forward into the new timeline shape:\n\n```bash\n# → local D1 by default, so you can test before touching prod\nBETO_PET_ID=pet_xxxxx bun run scripts/migrate-beto.ts\n\n# → a remote target instead\nTARGET_REMOTE=1 TARGET_DB=tama-\u003cpetslug\u003e TARGET_BUCKET=tama-\u003cpetslug\u003e-files \\\nBETO_PET_ID=pet_xxxxx bun run scripts/migrate-beto.ts\n```\n\nIt pulls each table from the source D1 as JSON, inserts only the columns that\nexist in the new schema (so `episode_id` is dropped and everything re-keys onto\n`pet_self`), mirrors the R2 blobs, and wipes the single-pet target first so it's\nidempotent. See [`scripts/migrate-beto.ts`](./scripts/migrate-beto.ts).\n\nTo (re-)extract lab PDFs into charted metrics — e.g. a hemoglobin trend the old\ndeploy never captured — run the worker and feed the files through `exam_upload`:\n\n```bash\nbun run dev   # worker on :8788, in another terminal\nbun run scripts/ingest-exams.ts ~/Downloads/exam1.pdf ~/Downloads/exam2.pdf\n```\n\n## MCP tools\n\nEvery tool acts on **the** pet (no `petId` argument anywhere).\n\n| Tool                        | What it does                                  |\n| --------------------------- | --------------------------------------------- |\n| `app_pet` / `app_timeline` / `app_timetable` | The three top-level apps      |\n| `pet_profile` / `pet_update`| Read / patch the singleton pet                |\n| `pet_enrich`                | Perplexity breed/condition research           |\n| `pet_summary_refresh`       | Regenerate the one evolving health summary    |\n| `pet_sprite_svg_generate`   | 6-state procedural-SVG companion sprite from a photo (saves v1) |\n| `pet_sprite_get` / `pet_sprite_adjust` | Read / iterate sprite traits (re-render, no new photo) |\n| `timeline_get`              | The merged continuous timeline                |\n| `timeline_note_add`         | Add a free-form timeline note                 |\n| `vet_visit_add` / `_list`   | Log / read vet visits                         |\n| `vaccine_add` / `_list`     | Log / read vaccinations                       |\n| `symptom_add` / `_resolve` / `_list` | Log / resolve / read symptoms        |\n| `asset_upload` / `asset_list` | Drop any file → classified into the timeline |\n| `prescription_upload` / `_create` / `_update` / `_list` / `_delete` | Prescriptions |\n| `timetable_get`             | Derived live timetable for next N hours       |\n| `dose_log` / `dose_update`  | Log given / skipped / undone                  |\n| `schedule_state_list` / `_delete` | Read / remove live item state           |\n| `timetable_snooze` / `_set_anchor` / `_set_duration` / `_stop_item` | Per-item adjustments |\n| `recording_*`               | Audio chunked upload → whisper → summary      |\n| `exam_upload` / `_paste` / `_get` / `_list` / `_update` / `_delete` | Lab exams |\n| `exam_metric_series`        | Chart-shaped per-metric time series           |\n| `vet_research`              | Perplexity with auto-attached pet + meds context |\n| `push_*`                    | VAPID key, subscribe, unsubscribe, test       |\n\n## Tests\n\n```bash\nbun test          # unit tests (timetable + exam-metric chunking + state)\nbun run check     # tsc --noEmit\nbun run ci:check  # biome\n```\n\n## Non-goals\n\n- Multi-pet households on one deploy. Two pets → two forks → two deploys.\n  See [the plan doc](./docs/) for the rationale.\n- Selling this as a managed service. The deployment story is fork-and-run.\n- Native iOS/Android apps. PWA only.\n\n## Acknowledgements\n\nBuilt on [deco studio](https://studio.decocms.com). The MCP runtime, the\nagent surface, and the \"Studio is the full lifecycle IDE\" thesis come\nfrom there. Tama is the personal-use side of the same primitives.\n\n[See AGENTS.md](./AGENTS.md) for the setup lifecycle.\n[See docs/](./docs/) for the open feature requests to the Studio team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Ftama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecocms%2Ftama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Ftama/lists"}