{"id":35212110,"url":"https://github.com/captainsafia/stitch","last_synced_at":"2026-04-07T13:32:19.649Z","repository":{"id":331005261,"uuid":"1124287085","full_name":"captainsafia/stitch","owner":"captainsafia","description":"Stitch is an intention tracking tool for agents and humans, helping bring semantic and contextual meaning to textual diffs.","archived":false,"fork":false,"pushed_at":"2025-12-31T21:32:30.000Z","size":46165,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T22:35:32.004Z","etag":null,"topics":["agents","ai","bun","git","intent-tracking","typescript"],"latest_commit_sha":null,"homepage":"","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/captainsafia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-28T18:17:32.000Z","updated_at":"2026-01-01T05:07:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/captainsafia/stitch","commit_stats":null,"previous_names":["captainsafia/stitch"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/captainsafia/stitch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainsafia%2Fstitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainsafia%2Fstitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainsafia%2Fstitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainsafia%2Fstitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/captainsafia","download_url":"https://codeload.github.com/captainsafia/stitch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captainsafia%2Fstitch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31515144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["agents","ai","bun","git","intent-tracking","typescript"],"created_at":"2025-12-29T19:21:44.139Z","updated_at":"2026-04-07T13:32:19.633Z","avatar_url":"https://github.com/captainsafia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :thread: stitch: the intent log for agents and humans\n\n![stitch demo](./demo.gif)\n\nStitch is a tool to help agents (and humans!) record their **intent** (\"stitches\") and bind it to **git commits/diffs**, forming an **intent DAG** that can't be represented by git's linear history or the textual representation of a diff.\n\nStitch helps you capture the \"why\" behind your code changes, creating a semantic layer on top of git that connects you and your agents' intentions to your implementations.\n\n## Features\n\n- **Intent Tracking**: Create and manage \"stitches\" - documents that capture the intent behind code changes\n- **Git Integration**: Link stitches to commits, commit ranges, and staged diffs\n- **DAG Relationships**: Build hierarchical relationships with parent/child stitches and dependencies\n- **Stitch Blame**: See which intent is behind each line of code\n- **MCP Server**: Expose stitch functionality to AI agents via the Model Context Protocol\n\n## Installation\n\n### Binary (Recommended)\n\n** \n```bash\ncurl -fsSL https://raw.githubusercontent.com/captainsafia/stitch/main/scripts/install.sh | bash -s -- --preview\n```\n\n**Install CLI only**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/captainsafia/stitch/main/scripts/install.sh | bash -s -- --preview --cli-only\n```\n\n**Install MCP server only**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/captainsafia/stitch/main/scripts/install.sh | bash -s -- --preview --mcp-only\n```\n\n### Building from Source\n\n```bash\ngit clone https://github.com/captainsafia/stitch.git\ncd stitch\nbun install\nbun run compile\n```\n\n## Quick Start\n\n```bash\n# Initialize stitch in your repository\nstitch init\n\n# Start a new stitch session\nstitch start \"Implement user authentication\"\n\n# Work on your code, then link commits\ngit add .\ngit commit -m \"Add login form\"\nstitch link --commit HEAD\n\n# Create a child stitch for sub-tasks\nstitch child \"Add password validation\"\n\n# See stitch attribution for any file\nstitch blame src/auth.ts\n```\n\n## Commands\n\n### Session Management\n\n#### `stitch init`\n\nInitialize stitch in the current git repository. Creates the `.stitch/` directory structure.\n\n#### `stitch start \u003ctitle\u003e`\n\nStart a new stitch session with the given title. Sets this as the current stitch.\n\n```bash\nstitch start Implement user authentication\n```\n\n#### `stitch child \u003ctitle\u003e`\n\nCreate a child stitch under the current stitch. Useful for breaking down larger tasks.\n\n```bash\nstitch child \"Add password validation\"\n```\n\n#### `stitch switch \u003cid\u003e`\n\nSwitch to a different stitch by ID.\n\n```bash\nstitch switch S-20251228-3f2a\n```\n\n#### `stitch status`\n\nShow the current stitch and its lineage (ancestor chain).\n\n### Viewing Stitches\n\n#### `stitch list [--status \u003cstatus\u003e]`\n\nList all stitches, optionally filtered by status.\n\n```bash\nstitch list\nstitch list --status open\nstitch list --status closed\n```\n\n**Status options:** `open`, `closed`, `superseded`, `abandoned`\n\n#### `stitch show \u003cid\u003e`\n\nShow details of a specific stitch.\n\n```bash\nstitch show S-20251228-3f2a\n```\n\n#### `stitch edit [id]`\n\nOpen a stitch in your editor. Defaults to the current stitch.\n\n```bash\nstitch edit\nstitch edit S-20251228-3f2a\n```\n\n### Linking to Git\n\n#### `stitch link --commit \u003csha\u003e`\n\nLink a specific commit to the current stitch (or specify `--id`).\n\n```bash\nstitch link --commit HEAD\nstitch link --commit abc1234\nstitch link --commit HEAD --id S-20251228-3f2a\n```\n\n#### `stitch link --range \u003crange\u003e`\n\nLink a commit range to the current stitch.\n\n```bash\nstitch link --range origin/main..HEAD\n```\n\n#### `stitch link --staged`\n\nCreate a fingerprint of the current staged diff and link it to the current stitch.\n\n```bash\nstitch link --staged\n```\n\n### Blame\n\n#### `stitch blame \u003cpath\u003e [--format plain|json]`\n\nShow stitch attribution for each line in a file.\n\n```bash\nstitch blame src/auth.ts\nstitch blame src/auth.ts --format json\n```\n\n## Stitch File Format\n\nStitches are stored as Markdown files with TOML frontmatter in `.stitch/stitches/`:\n\n```markdown\n+++\nid = \"S-20251228-3f2a\"\ntitle = \"Implement user authentication\"\nstatus = \"open\"\ncreated_at = \"2025-12-28T22:41:00-08:00\"\nupdated_at = \"2025-12-28T22:41:00-08:00\"\nprovenance = \"human\"\nconfidence = \"medium\"\ntags = [\"auth\", \"security\"]\n\n[relations]\nparent = \"S-20251228-aaaa\"\n\n[git]\nlinks = [\n  { kind = \"commit\", sha = \"deadbeef...\" },\n]\n+++\n\n## Intent\n\nImplement secure user authentication with session management.\n\n## Constraints\n\n- Must use bcrypt for password hashing\n- Sessions expire after 24 hours\n\n## Notes\n\nConsider adding OAuth support in a future iteration.\n```\n\n## Library Usage\n\nStitch can also be used as a TypeScript library:\n\n```typescript\nimport { StitchClient } from '@captainsafia/stitch';\n\nconst client = new StitchClient();\n\n// Initialize and create stitches\nawait client.init();\nconst stitch = await client.start(\"My feature\");\n\n// Link commits\nawait client.linkCommit(\"abc1234\");\n\n// Get blame information\nconst blame = await client.blame(\"src/file.ts\");\nfor (const line of blame) {\n  console.log(`Line ${line.line}: ${line.stitchIds.join(\", \") || \"unstitched\"}`);\n}\n\nclient.close();\n```\n\n## MCP Server\n\nStitch includes an MCP (Model Context Protocol) server that allows AI agents to interact with stitch functionality programmatically. The MCP server exposes stateless, explicit tools that don't rely on \"current stitch\" state.\n\n### Running the MCP Server\n\n```bash\n# Start the MCP server (stdio transport)\nstitch-mcp\n```\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `stitch_create` | Create a new stitch document |\n| `stitch_get` | Get a stitch by ID |\n| `stitch_list` | List stitches with optional filters |\n| `stitch_update_frontmatter` | Update stitch metadata |\n| `stitch_update_body` | Update stitch markdown body |\n| `stitch_link_commit` | Link a commit to a stitch |\n| `stitch_link_range` | Link a commit range to a stitch |\n| `stitch_link_staged_diff` | Link staged diff fingerprint |\n| `stitch_blame` | Get stitch attribution for file lines |\n\n### Example Tool Usage\n\nAll tools require explicit `repoRoot` and `stitchId` parameters (no implicit state):\n\n```json\n{\n  \"tool\": \"stitch_create\",\n  \"arguments\": {\n    \"repoRoot\": \"/path/to/repo\",\n    \"title\": \"Implement new feature\"\n  }\n}\n```\n\n```json\n{\n  \"tool\": \"stitch_link_commit\",\n  \"arguments\": {\n    \"repoRoot\": \"/path/to/repo\",\n    \"stitchId\": \"S-20251228-3f2a\",\n    \"sha\": \"abc1234\"\n  }\n}\n```\n\n### Configuring with AI Agents\n\nTo use stitch-mcp with an MCP-compatible AI agent, add it to your agent's MCP server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"stitch\": {\n      \"command\": \"stitch-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n## Configuration\n\nStitch stores all data in your repository under `.stitch/`:\n\n```\n.stitch/\n├── current          # Current stitch ID\n└── stitches/        # Stitch documents\n    └── S-YYYYMMDD-xxxx.md\n```\n\n**Environment Variables:**\n\n- `EDITOR` or `VISUAL` - Editor for `stitch edit` command\n- `DEBUG=1` - Enable debug output with stack traces\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/captainsafia/stitch.git\ncd stitch\nbun install\n```\n\n### Testing\n\n```bash\nbun test           # Run all tests\nbun run typecheck  # Type checking\n```\n\n### Building\n\n```bash\nbun run build      # Build for npm distribution\nbun run compile    # Compile standalone binary\n```\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptainsafia%2Fstitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaptainsafia%2Fstitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptainsafia%2Fstitch/lists"}