{"id":51024217,"url":"https://github.com/jueduizone/agentthread","last_synced_at":"2026-06-21T18:02:15.191Z","repository":{"id":354015178,"uuid":"1221744515","full_name":"jueduizone/agentthread","owner":"jueduizone","description":"Persistent collaboration threads for multi-agent systems","archived":false,"fork":false,"pushed_at":"2026-04-26T17:43:40.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T19:22:36.085Z","etag":null,"topics":["a2a","agents","collaboration","memory","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/jueduizone.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":null,"dco":null,"cla":null}},"created_at":"2026-04-26T16:17:49.000Z","updated_at":"2026-04-26T17:43:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jueduizone/agentthread","commit_stats":null,"previous_names":["jueduizone/agentthread"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jueduizone/agentthread","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jueduizone%2Fagentthread","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jueduizone%2Fagentthread/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jueduizone%2Fagentthread/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jueduizone%2Fagentthread/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jueduizone","download_url":"https://codeload.github.com/jueduizone/agentthread/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jueduizone%2Fagentthread/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34620358,"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-21T02:00:05.568Z","response_time":54,"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":["a2a","agents","collaboration","memory","sqlite"],"created_at":"2026-06-21T18:02:14.217Z","updated_at":"2026-06-21T18:02:15.176Z","avatar_url":"https://github.com/jueduizone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentThread\n\nPersistent collaboration threads for multi-agent systems.\n\nAgents can already talk through A2A, gateway APIs, webhooks, IM bots, or task systems. The hard part is remembering who owns the work, what another agent replied, what the latest status is, and what to say when the user later asks \"progress?\"\n\nAgentThread is a small local-first state layer for delegation, consultation, handoff, and progress recall. MVP0 is a Python package and JSON CLI backed by SQLite. Runtime code uses only the Python standard library.\n\n## Install\n\nFor local development:\n\n```bash\npython -m pip install -e .\n```\n\nFor one-off use without installing:\n\n```bash\npython -m agentthread.cli --help\n```\n\nAgentThread stores its default database at:\n\n```text\n~/.agent-thread/agentthread.db\n```\n\nUse `--db /path/to/agentthread.db` for tests, experiments, or isolated agent runtimes.\n\n## Development\n\n```bash\npython -m pytest\n```\n\nThe project has no runtime dependencies beyond Python and SQLite from the standard library. Test tooling is intentionally outside the package runtime contract.\n\n## Quickstart\n\nFor stable agent collaboration, use the high-level workflow CLI first:\n\n- `agentthread task create` — work delegation; must use a task backend.\n- `agentthread ask` — consultation/review; always records an AgentThread.\n- `agentthread notify` — human notification; rejects agent targets.\n- `agentthread audit` — flags raw A2A transcripts without AgentThread state.\n- `agentthread doctor` — checks local readiness and optional `agentthread.yaml`.\n- `agentthread policy` — prints active workflow guardrails.\n- `agentthread init` — writes a starter `agentthread.yaml`.\n\nThe lower-level `agent-thread` CLI remains available for direct state inspection and repair.\n\nCreate a thread when one agent owns a user request and another participant needs to help:\n\n```bash\nagent-thread create \\\n  --type task \\\n  --owner prd-bot \\\n  --participant product-dev \\\n  --created-by ian \\\n  --source-platform telegram \\\n  --source-chat 409747388 \\\n  --topic \"HackAgent QA accounts\" \\\n  --summary \"Ian asked Product Agent to get Dev Agent to create QA accounts.\"\n```\n\nUpdate the current state:\n\n```bash\nagent-thread update thr_xxx \\\n  --status waiting_on_participant \\\n  --next-actor product-dev \\\n  --next-action \"Create accounts and update issue\" \\\n  --summary \"Dev Agent is creating QA accounts.\"\n```\n\nAppend an event:\n\n```bash\nagent-thread event append thr_xxx \\\n  --type message_sent \\\n  --actor prd-bot \\\n  --target product-dev \\\n  --summary \"Asked Dev Agent to create QA accounts.\"\n```\n\nRecall likely context when a user asks a vague follow-up:\n\n```bash\nagent-thread answer-context \\\n  --owner prd-bot \\\n  --query \"progress?\" \\\n  --source-platform telegram \\\n  --source-chat 409747388\n```\n\nAll commands print JSON.\n\n## CLI Examples\n\nFetch a thread:\n\n```bash\nagent-thread get thr_xxx\n```\n\nList events:\n\n```bash\nagent-thread events thr_xxx\n```\n\nExport a full thread record with its event log:\n\n```bash\nagent-thread export thr_xxx\n```\n\nList recent owner threads:\n\n```bash\nagent-thread recent --owner prd-bot --limit 10\n```\n\nList and mark inbox items:\n\n```bash\nagent-thread inbox list --agent product-dev\nagent-thread inbox read inb_xxx\n```\n\nPass structured fields as JSON during creation:\n\n```bash\nagent-thread create \\\n  --type task \\\n  --owner prd-bot \\\n  --participant product-dev \\\n  --topic \"Structured delegation\" \\\n  --json '{\"created_by\":{\"type\":\"human\",\"id\":\"ian\"},\"source\":{\"platform\":\"telegram\",\"chat_id\":\"409747388\"},\"next_action\":{\"actor\":\"product-dev\",\"description\":\"Reply with status\"},\"artifacts\":[{\"type\":\"linear_issue\",\"id\":\"AT-1\"}],\"tags\":[\"agentthread\"],\"metadata\":{\"priority\":1}}'\n```\n\nUpdate structured fields:\n\n```bash\nagent-thread update thr_xxx \\\n  --json '{\"next_action\":{\"actor\":\"prd-bot\",\"description\":\"Follow up\"},\"metadata\":{\"priority\":2}}'\n```\n\n## How It Relates\n\nA2A and webhooks move messages between agents. AgentThread records ownership, status, events, next actions, and artifacts so the owner can answer later.\n\nIM platforms such as Telegram, Slack, Discord, Feishu, and Matrix are entry points or notification surfaces. They are not the source of truth.\n\nSQLite is the MVP source of truth because it gives deterministic IDs, updates, filters, ordering, foreign keys, and append-only event history without running a server.\n\nMemory systems are complementary. Use memory or vector recall for fuzzy long-term summaries; use AgentThread for canonical active collaboration state.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjueduizone%2Fagentthread","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjueduizone%2Fagentthread","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjueduizone%2Fagentthread/lists"}