{"id":50216212,"url":"https://github.com/fgrehm/lazychat","last_synced_at":"2026-05-26T09:04:19.439Z","repository":{"id":352966680,"uuid":"1212902078","full_name":"fgrehm/lazychat","owner":"fgrehm","description":"File-based async discussion protocol for pair programming with AI agents.","archived":false,"fork":false,"pushed_at":"2026-05-04T21:47:39.000Z","size":244,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-04T22:25:32.429Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgrehm.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-04-16T21:04:19.000Z","updated_at":"2026-04-30T15:39:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fgrehm/lazychat","commit_stats":null,"previous_names":["fgrehm/lazychat"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fgrehm/lazychat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Flazychat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Flazychat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Flazychat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Flazychat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgrehm","download_url":"https://codeload.github.com/fgrehm/lazychat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Flazychat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33512343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T03:12:49.672Z","status":"ssl_error","status_checked_at":"2026-05-26T03:12:47.976Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-05-26T09:04:01.189Z","updated_at":"2026-05-26T09:04:19.430Z","avatar_url":"https://github.com/fgrehm.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lazychat\n\nFile-based async discussion protocol for pair programming with AI agents.\n\n## What it is\n\nA shared markdown file in your working tree where an AI agent writes questions or proposals, and you reply at your own pace. The file is the thread.\n\n## Why\n\nChat is lossy for multi-decision work:\n\n- **Context rot.** Replies re-quote what they are answering because the original scrolls away.\n- **Sequential forcing.** Chat is LIFO. The human has to answer in chat order, not their own order.\n- **No persistent artifact.** Chat transcripts are hard to revisit. A file can be re-opened, git-tracked, and referenced later.\n- **Proposals get paraphrased on reply.** The agent cannot verify its own proposal landed intact.\n\nChat is also harder on people who can't keep its pace. Rapid-fire messaging expects real-time reading, fast typing, and uninterrupted attention; a markdown thread does not. You can walk away, read with a screen reader, take hours to compose a reply, and the agent waits without nagging.\n\nCheck out [this blog post](https://fabiorehm.com/blog/2026/04/17/lazychat/) for more background.\n\n## How it works\n\n1. Agent creates a file at `.lazyai/YYYY-MM-DDTHHMM-topic.md`.\n2. Agent writes questions, proposals, or drafts in the file, then stops and tells you.\n3. You reply in the file, freeform. No required structure.\n4. Agent reads the file back in full and continues.\n\nThe protocol is tooling-agnostic. Any agent that reads and writes files, and any human with a text editor, can run it.\n\nSee [`examples/`](examples/) for completed threads from lazychat's own design sessions.\n\n## Installation\n\nThere are two ways to use lazychat: with the CLI, or with just the skill file.\n\n### With the CLI (recommended)\n\nDownload the binary for your platform from the [latest release](https://github.com/fgrehm/lazychat/releases/latest) and put it on your `PATH`:\n\n```bash\n# Linux x64 (adapt for darwin-arm64, etc.)\nwget https://github.com/fgrehm/lazychat/releases/download/v0.0.3/lazychat-linux-x64 \\\n  -O ~/.local/bin/lazychat\nchmod +x ~/.local/bin/lazychat\n```\n\nThe binary is self-contained (the Bun runtime is bundled), no other dependencies.\n\nThen install the CLI skill for your agent. The skill is bundled with the binary, so just dump it:\n\n```bash\n# Claude Code\nmkdir -p .claude/skills/lazychat\nlazychat skill \u003e .claude/skills/lazychat/SKILL.md\n```\n\nThe CLI-backed skill is shorter and simpler: the agent shells out instead of editing raw markdown, and `lazychat onboard` gives it the full protocol reference at session start.\n\n### Skill only (no CLI required)\n\nIf you prefer not to install a binary, the file-based skill works without it. The agent reads and writes the thread files directly using the format described in `SKILL.md`.\n\n```bash\n# Claude Code\nmkdir -p .claude/skills/lazychat\nwget https://github.com/fgrehm/lazychat/raw/refs/tags/v0.0.3/SKILL.md \\\n  -O .claude/skills/lazychat/SKILL.md\n```\n\n## CLI reference\n\n```\nlazychat new \u003ctopic-slug\u003e [--context -]\n```\nCreate a new thread. Prints the file path. `--context -` reads one paragraph of context from stdin.\n\n```\nlazychat reply \u003cfile\u003e --as \u003cagent|human\u003e [--model \u003cid\u003e] [--stdin | --body \u003cstr\u003e | --editor]\n```\nAppend a turn. `--as` is required. Exactly one body source (`--stdin`, `--body`, or `--editor`). `--model` is for agent turns. `--editor` is human-only and opens `$EDITOR` with the last turn pre-quoted; it is also the default when `--as human` is given with no body source. Empty or unchanged buffer aborts without appending.\n\n```\nlazychat open \u003cfile\u003e\n```\nOpen a thread file in `$EDITOR` for reading or manual editing.\n\n```\nlazychat converge \u003cfile\u003e --stdin | --body \u003cstr\u003e\n```\nAppend an Outcome section and mark the thread converged. Exactly one of `--stdin` or `--body` must be given.\n\n```\nlazychat show \u003cfile\u003e [--turn N | --last [N]]\n```\nPrint thread content. No flag prints the whole file. `--turn N` prints the turn(s) with id N (the parser tolerates duplicate ids). `--last [N]` prints the trailing N turns (default 1) — useful catch-up after the other side has written.\n\n```\nlazychat list [--status open|converged|all] [--json]\n```\nList threads in `.lazyai/`, most recent first. Defaults to open threads.\n\n```\nlazychat status \u003cfile\u003e [--json]\n```\nPrint frontmatter, turn count, and last-updated timestamp.\n\n```\nlazychat onboard\n```\nPrint the protocol reference and active threads. Run this at the start of an agent session.\n\n```\nlazychat skill\n```\nPrint the bundled `SKILL-CLI.md` to stdout. Useful for installing the skill into an agent's skills directory without a download step.\n\n## Related work\n\nlazychat sits next to a handful of projects that use shared markdown files as agent state, but differs in focus:\n\n- [tick-md](https://purplehorizons.io/blog/tick-md-multi-agent-coordination-markdown): multi-agent coordination via a shared markdown task board. Agent-to-agent, with file locking, an MCP server, and a dashboard.\n- [llm-md](https://llm.md/): a DSL for LLM-to-LLM conversations in markdown. Structured agent turns with explicit syntax.\n- Basic Memory: bidirectional LLM-markdown knowledge persistence via MCP. Knowledge-graph shape, not discussion shape.\n\nlazychat is narrower: human plus agent, freeform replies, explicit stop-and-wait, file-as-record.\n\n## Status\n\nDistilled from real use with pi coding agent and Claude Code. Deliberately minimal.\n\nv0.0.3 added a TypeScript + Bun rewrite with a full CLI (`lazychat`) and a companion skill (`SKILL-CLI.md`) for agents that have it installed. The file-based `SKILL.md` remains for environments where the CLI is not available.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Flazychat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgrehm%2Flazychat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Flazychat/lists"}