{"id":46554036,"url":"https://github.com/fardjad/context-dropper","last_synced_at":"2026-03-11T07:00:48.160Z","repository":{"id":342725418,"uuid":"1172314515","full_name":"fardjad/context-dropper","owner":"fardjad","description":"A CLI for iterating through a fixed list of files, tracking position, and tagging progress.","archived":false,"fork":false,"pushed_at":"2026-03-09T04:02:46.000Z","size":102,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T08:03:23.116Z","etag":null,"topics":["ai-agents","cli","llm-context","opencode-plugin"],"latest_commit_sha":null,"homepage":"","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/fardjad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-03-04T07:01:01.000Z","updated_at":"2026-03-09T04:02:49.000Z","dependencies_parsed_at":"2026-03-10T06:00:35.446Z","dependency_job_id":null,"html_url":"https://github.com/fardjad/context-dropper","commit_stats":null,"previous_names":["fardjad/context-dropper"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/fardjad/context-dropper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardjad%2Fcontext-dropper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardjad%2Fcontext-dropper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardjad%2Fcontext-dropper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardjad%2Fcontext-dropper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fardjad","download_url":"https://codeload.github.com/fardjad/context-dropper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardjad%2Fcontext-dropper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30326878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"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":["ai-agents","cli","llm-context","opencode-plugin"],"created_at":"2026-03-07T04:03:45.658Z","updated_at":"2026-03-10T06:00:41.596Z","avatar_url":"https://github.com/fardjad.png","language":"TypeScript","readme":"# context-dropper\n\n`context-dropper` is a CLI for iterating through a fixed list of files, tracking\nposition, and tagging progress.\n\n## Why Context Dropper?\n\nAI coding agents struggle with large codebases in two main ways:\n\n1. **Search doesn't guarantee coverage:** Agents often rely on semantic or\n   keyword search to find relevant files, and it works well in many cases. But\n   for tasks that require iterating over every file in a set, there is no\n   guarantee that search alone will find them all.\n2. **Context windows are a hard constraint:** Feeding an entire codebase into an\n   LLM at once is often simply impossible. Codebases frequently exceed the\n   model's token limit. Even when it fits, reasoning quality degrades as the\n   context grows.\n\n`context-dropper` solves this by enforcing strict, programmable processing\nloops.\n\nInstead of relying on search, a precise list of target files (a \"fileset\") is\ncurated upfront - either manually or by using other tools - and the agent is\ninstructed to process that exact list sequentially. As the agent moves from one\nfile to the next, it can drop the previous file's tokens from memory. Each file\nis then evaluated in a **clean context**.\n\nThis approach guarantees 100% file coverage, minimizes token usage, and keeps\nthe model's reasoning sharp.\n\n### A Conceptual Example\n\nConsider an agent tasked with exploring a large codebase to document every piece\nof authentication logic it finds into a single file\n(`authentication-discovery.md`). Without `context-dropper`, the agent would use\nsearch to find files containing keywords like \"auth\", \"login\", or \"session\", and\nmight miss files that contain authentication logic but don't match those\nkeywords. With `context-dropper`, the agent instead iterates over a fixed,\ncurated list of files, such as all files in a subdirectory or a filtered list\nfrom a test coverage report.\n\nHere is how that looks in practice:\n\n1. **The Fileset**: A discrete list of target files is provided to the tool:\n   - `src/auth/login.ts`\n   - `src/routes/api.ts`\n   - `src/middleware/session.ts`\n2. **The Dropper**: A \"dropper\" is created and attached to that fileset. The\n   dropper acts as a stateful bookmark that tracks exactly where the agent is in\n   the list (it can go forward or backward).\n3. **The Loop**: The AI agent is given a strict set of instructions: _\"Read the\n   current file from the dropper. If authentication logic is found, append the\n   findings to `authentication-discovery.md`. Then mark the file as 'processed',\n   and move the dropper to the next file until the list is exhausted.\"_\n\nBy explicitly unloading the previous file from its context window before moving\nthe dropper, the context size remains small. This prevents the LLM from blowing\npast its token limits or suffering from degraded reasoning. In theory, an\nunlimited number of files can be processed this way.\n\n## Installation\n\nYou can install `context-dropper` using one of the following methods.\n\n### 1. Download Pre-compiled Binary (Recommended)\n\nDownload the latest standalone executable for your operating system from the\n[Releases](https://github.com/fardjad/context-dropper/releases) page. Ensure it\nis executable and in your `PATH`.\n\n```bash\nchmod +x context-dropper\nmv context-dropper /usr/local/bin/\n```\n\n### 2. Install via Package Manager\n\nYou can install the package globally from NPM.\n\n**Bun:**\n\n```bash\nbun install -g context-dropper\n```\n\n**NPM:**\n\n```bash\nnpm install -g context-dropper\n```\n\nThen run it anywhere:\n\n```bash\ncontext-dropper --help\n```\n\n### 3. Build from Source (Development)\n\nTo develop, compile binaries from source, or contribute to the project, please\nrefer to the [Contributing Guide](CONTRIBUTING.md).\n\n## Command Shape\n\n```bash\ncontext-dropper [--data-dir \u003cpath\u003e] \u003ccommand\u003e\n```\n\nGlobal option:\n\n- `--data-dir \u003cpath\u003e`: directory where filesets and droppers are stored.\n- Default: `./.context-dropper` resolved from current working directory.\n\nIf run with no command, usage/help is shown. If `fileset` or `dropper` are run\nwithout a subcommand, that group help is shown.\n\n## Data Layout\n\nThe CLI stores state under `data-dir`:\n\n```text\ndata-dir/\n  filesets/\n    \u003cname\u003e.txt\n  droppers/\n    \u003cname\u003e.json\n```\n\nFileset file (`filesets/\u003cname\u003e.txt`):\n\n- One normalized absolute file path per line.\n- Import is immutable: importing the same fileset name again fails.\n\nDropper file (`droppers/\u003cname\u003e.json`):\n\n```json\n{\n  \"fileset\": \"my-fileset\",\n  \"pointer_position\": 0,\n  \"tags\": {\n    \"processed\": [\"/abs/path/a.ts\", \"/abs/path/b.ts\"]\n  }\n}\n```\n\n- `tags` is `tag -\u003e filename[]`.\n- Filename arrays are deduplicated and sorted.\n\n## Name Rules\n\nFileset/dropper names must:\n\n- Match `^[A-Za-z0-9._-]+$`\n- Not be `.` or `..`\n- Not contain path separators\n\n## Commands\n\n### `fileset`\n\nImport from a list file:\n\n```bash\ncontext-dropper fileset import --name \u003cname\u003e \u003clistFilePath\u003e\n```\n\n- `listFilePath` must be plain text with one path per line.\n- Blank lines are ignored.\n- Relative lines are resolved from the list file directory.\n- Each referenced file must exist and be readable.\n- Stored entries become normalized absolute paths.\n\nList filesets:\n\n```bash\ncontext-dropper fileset list\n```\n\n- Output: one fileset name per line.\n\nShow fileset contents:\n\n```bash\ncontext-dropper fileset show \u003cname\u003e\n```\n\n- Output: one file path per line.\n\nRemove fileset:\n\n```bash\ncontext-dropper fileset remove \u003cname\u003e\n```\n\n- Fails if any dropper still references it.\n\n### `dropper`\n\nCreate:\n\n```bash\ncontext-dropper dropper create --fileset \u003cfilesetName\u003e \u003cdropperName\u003e\n```\n\nShow current file contents:\n\n```bash\ncontext-dropper dropper show \u003cdropperName\u003e\n```\n\nMove pointer forward:\n\n```bash\ncontext-dropper dropper next \u003cdropperName\u003e\n```\n\n- Silent on success.\n\nMove pointer backward:\n\n```bash\ncontext-dropper dropper previous \u003cdropperName\u003e\n```\n\n- Silent on success.\n\nTag current item:\n\n```bash\ncontext-dropper dropper tag \u003cdropperName\u003e --tag \u003ctext\u003e [--tag \u003ctext\u003e]...\n```\n\nList tags of current item:\n\n```bash\ncontext-dropper dropper list-tags \u003cdropperName\u003e\n```\n\n- Output: one tag per line.\n\nRemove tags from current item:\n\n```bash\ncontext-dropper dropper remove-tag \u003cdropperName\u003e --tag \u003ctext\u003e [--tag \u003ctext\u003e]...\n```\n\nList dropper entries with optional filters:\n\n```bash\ncontext-dropper dropper list-files \u003cdropperName\u003e [--tag \u003ctag\u003e]... [--filename \u003cabsolutePath\u003e]\n```\n\n- Output: paths only, one per line.\n- Repeated `--tag` uses OR semantics.\n- `--filename` is exact path match.\n- When both are provided: AND semantics (`filename` match and tag OR match).\n- Aliases: `context-dropper dropper ls-files \u003cdropperName\u003e`\n\nList all droppers, optionally filtered by fileset name:\n\n```bash\ncontext-dropper dropper list [--fileset \u003cfilesetName\u003e]\n```\n\n- Output: one dropper name per line.\n- When `--fileset` is provided, filters for droppers referencing that fileset.\n- Aliases: `context-dropper dropper ls [--fileset \u003cfilesetName\u003e]`\n\nDump dropper materialized state:\n\n```bash\ncontext-dropper dropper dump \u003cdropperName\u003e\n```\n\n- Output: pretty JSON.\n\nRemove dropper:\n\n```bash\ncontext-dropper dropper remove \u003cdropperName\u003e\n```\n\nCheck completion:\n\n```bash\ncontext-dropper dropper is-done \u003cdropperName\u003e\n```\n\n- Done condition: every file has at least one tag.\n- If done: prints `true` and exits `0`.\n- If not done: exits non-zero with an error listing untagged files.\n\n## OpenCode Plugin\n\nThis repository also includes a dedicated, self-contained plugin for\n[OpenCode](https://github.com/opencode-ai/opencode) under `opencode-plugin/`.\nThe plugin natively binds to the `context-dropper` APIs and lets you iterate\nthrough filesets autonomously inside an OpenCode chat session. See\n[opencode-plugin/README.md](./opencode-plugin/README.md) for installation and\nusage instructions.\n\n## Exit Codes\n\n- `0`: success\n- `1`: application error\n- `2`: usage/argument error\n- `3`: dropper exhausted (`show` with no current item, or `next` at end)\n- `4`: dropper at start (`previous` at start)\n\n## Suggested AI-Agent Workflow\n\n1. Import a fileset:\n   `context-dropper fileset import --name \u003cfilesetName\u003e \u003clistFilePath\u003e`\n2. Create a dropper:\n   `context-dropper dropper create --fileset \u003cfilesetName\u003e \u003cdropperName\u003e`\n3. Ask the agent to perform the task (for example: review/document each file)\n   and follow the processing loop below.\n\n## Agent Loop Rule\n\nWhen acting as an agent over a dropper, use this exact loop:\n\n1. Run `context-dropper dropper show \u003cdropperName\u003e`.\n2. Perform the requested task on that file content.\n3. Run `context-dropper dropper tag \u003cdropperName\u003e --tag processed`.\n4. Run `context-dropper dropper is-done \u003cdropperName\u003e`.\n5. If `is-done` succeeded and printed `true`, stop.\n6. If `is-done` failed because untagged items remain, run\n   `context-dropper dropper next \u003cdropperName\u003e` and repeat from step 1.\n\nNotes for agents:\n\n- `next` and `previous` are movement only; they do not print file contents.\n- Use `show` to read the current file.\n- Do not stop on `is-done` non-zero unless the message is not\n  `Untagged items remain: ...`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffardjad%2Fcontext-dropper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffardjad%2Fcontext-dropper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffardjad%2Fcontext-dropper/lists"}