{"id":50434233,"url":"https://github.com/forjd/ctx","last_synced_at":"2026-05-31T16:03:06.048Z","repository":{"id":354744454,"uuid":"1224975305","full_name":"forjd/ctx","owner":"forjd","description":"Local context packs for coding agents","archived":false,"fork":false,"pushed_at":"2026-04-29T22:07:15.000Z","size":188,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T22:33:39.927Z","etag":null,"topics":["bun","cli","coding-agents","context-engine","developer-tools","laravel","typescript","vue"],"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/forjd.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-29T20:24:42.000Z","updated_at":"2026-04-29T22:07:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forjd/ctx","commit_stats":null,"previous_names":["forjd/ctx"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/forjd/ctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forjd","download_url":"https://codeload.github.com/forjd/ctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33737692,"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-05-31T02:00:06.040Z","response_time":95,"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":["bun","cli","coding-agents","context-engine","developer-tools","laravel","typescript","vue"],"created_at":"2026-05-31T16:03:04.681Z","updated_at":"2026-05-31T16:03:06.029Z","avatar_url":"https://github.com/forjd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ctx\n\n[![CI](https://github.com/forjd/ctx/actions/workflows/ci.yml/badge.svg)](https://github.com/forjd/ctx/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@forjd/ctx)](https://www.npmjs.com/package/@forjd/ctx)\n[![Coverage](https://img.shields.io/badge/coverage-95%25%2B-brightgreen)](scripts/check-coverage.ts)\n[![License: MIT](https://img.shields.io/github/license/forjd/ctx)](LICENSE)\n[![Bun](https://img.shields.io/badge/runtime-Bun-black?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/language-TypeScript-3178c6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Local First](https://img.shields.io/badge/local--first-no%20AI%20API-7c3aed)](#how-it-works)\n\nLocal context packs for coding agents.\n\n`ctx` is a deterministic CLI that scans a repository and generates the files, tests, rules, risks, and commands an agent should inspect before editing code. It is local-first, fast, and does not call an AI API.\n\n## Why\n\nCoding agents are more useful when they start with the right context. `ctx` gives them a compact, task-specific brief instead of asking them to wander through a whole repository.\n\nIt can:\n\n- detect Laravel, Symfony, WordPress, Drupal, Rails, Django, FastAPI, Flask, Go, Vue, React, Next.js, Nuxt, SvelteKit, Node HTTP, NestJS, Remix, React Router, Astro, TypeScript, and Pest projects\n- index important files and lightweight symbols\n- infer project rules from config and docs\n- rank task-relevant files with reasons\n- recommend focused tests\n- flag risky Git diffs\n- write handoff summaries after a run\n\n## Quick Start\n\nRun the published Bun CLI:\n\n```bash\nbunx @forjd/ctx --help\n```\n\nOr install it globally:\n\n```bash\nbun add --global @forjd/ctx\nctx --help\n```\n\nFrom a source checkout:\n\n```bash\ngit clone https://github.com/forjd/ctx.git\ncd ctx\nbun install\n\n# Run ctx from this checkout\nbun run ctx --help\n```\n\nAgainst another repository:\n\n```bash\ncd /path/to/your/repo\nctx init\nctx index\nctx pack \"add expiry reminders for source-of-funds requests\"\n```\n\n## Example\n\n```bash\nctx pack \"add retry handling for report exports\"\n```\n\nProduces a Markdown context pack with:\n\n- relevant files, each with a reason\n- related tests and exact commands\n- inferred project rules\n- matching Git history\n- risk notes\n- suggested next actions\n\nAgent-optimized output is available with `--agent`:\n\n```bash\nctx pack \"add retry handling for report exports\" --agent\n```\n\nFor `ctx pack`, `--agent` emits compact JSON using the small pack limits by default and avoids\nwriting saved pack files. JSON payloads include `schemaVersion` so agents can parse them\ndefensively as `ctx` evolves.\n\n## Commands\n\n| Command                                     | Purpose                                                                   |\n| ------------------------------------------- | ------------------------------------------------------------------------- |\n| `ctx init`                                  | Create `.ctx/`, SQLite storage, config, packs, and handoff directories.   |\n| `ctx index`                                 | Scan files, extract lightweight symbols, infer rules, and store metadata. |\n| `ctx map [--json\\|--agent]`                 | Print detected stack, important directories, and conventions.             |\n| `ctx pack \u003ctask\u003e`                           | Generate a task-specific context pack in Markdown or JSON.                |\n| `ctx tests-for \u003cfile\u003e [--json\\|--agent]`    | Recommend focused test commands for a file.                               |\n| `ctx tests-for --changed [--json\\|--agent]` | Recommend tests for the current Git diff.                                 |\n| `ctx diff-risk [--json\\|--agent]`           | Classify changed files and report risk signals.                           |\n| `ctx rules [--json\\|--agent]`               | Print inferred project rules.                                             |\n| `ctx explain \u003cfile\u003e [--json\\|--agent]`      | Explain one indexed file's category, symbols, tests, and rules.           |\n| `ctx stale [--json\\|--agent]`               | Report whether the saved index is stale for files, config, or Git HEAD.   |\n| `ctx handoff`                               | Write a Markdown handoff under `.ctx/handoffs/`.                          |\n\nUseful options:\n\n```bash\nctx pack \"task\" --agent\nctx pack \"task\" --json\nctx pack \"task\" --changed --json\nctx pack \"task\" --markdown\nctx pack \"task\" --small\nctx pack \"task\" --full --include-symbols\nctx pack \"task\" --files 20\nctx pack \"task\" --output .ctx/packs/my-task.md\nctx tests-for --changed --agent\nctx handoff --stdout\n```\n\nProject-specific scoring can be tuned in `.ctx/config.json` with `scoring.synonyms`,\n`scoring.categoryBoosts`, and `scoring.broaderTestCommands`.\n\n## How It Works\n\n`ctx` uses simple local heuristics:\n\n- path-based framework and category detection\n- lightweight regex symbol extraction\n- keyword and synonym matching\n- lightweight import/dependency edge extraction\n- test filename/domain similarity\n- Git diff and history inspection\n- SQLite storage via `bun:sqlite`\n\nThere are no embeddings, hosted services, background daemons, or external AI calls.\n\n## Supported Today\n\nBest coverage:\n\n- Laravel apps\n- Symfony apps\n- WordPress plugins and themes\n- Drupal modules and themes\n- Rails apps\n- Django apps\n- FastAPI apps\n- Flask apps\n- Go projects\n- Vue frontends\n- React and Next.js frontends\n- Nuxt applications\n- Svelte and SvelteKit frontends\n- Express, Fastify, and Hono services\n- NestJS applications\n- Remix and React Router applications\n- Astro sites\n- TypeScript and JavaScript projects\n- Pest/PHPUnit-style test layouts\n- general Git repositories\n\nThe project remains intentionally small: a deterministic context engine that improves agent setup before code edits.\n\n## Agent Skill\n\nThis repo includes a `ctx-context-pack` skill for agents that need a standard workflow for calling `ctx` before editing another repository.\n\nInstall it with [`bunx skills`](https://skills.sh/):\n\n```bash\nbunx skills add forjd/ctx --skill ctx-context-pack\n```\n\nTo install it for all supported agents without prompts:\n\n```bash\nbunx skills add forjd/ctx --skill ctx-context-pack --agent '*' -y\n```\n\nYou can inspect available skills first:\n\n```bash\nbunx skills add forjd/ctx --list\n```\n\n## Development\n\n```bash\nbun install\nbun run check\n```\n\nCommon scripts:\n\n```bash\nbun run ctx --help\nbun run typecheck\nbun run lint\nbun run format\nbun test\n```\n\nThe test suite includes Laravel and Vue fixtures under `tests/fixtures/`.\n\n## Contributing\n\nIssues and small PRs are welcome. Keep changes boring, deterministic, and easy to inspect.\n\nBefore opening a PR:\n\n```bash\nbun run check\n```\n\nCommits use Conventional Commits:\n\n```txt\nfeat: add context pack command\nfix: improve Laravel test discovery\nchore: update tooling\n```\n\n## Releases\n\nRelease PRs are managed by Release Please on pushes to `main`, and package publishing uses npm trusted publishing from GitHub Actions.\n\nIt uses Conventional Commits to update `package.json`, maintain `CHANGELOG.md`, tag the release, create the GitHub release, and publish `@forjd/ctx` to npm when the release PR is merged. The workflow can run with the default `GITHUB_TOKEN`; configure a `RELEASE_PLEASE_TOKEN` repository secret if Release Please PRs need to trigger other GitHub Actions workflows.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforjd%2Fctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fctx/lists"}