{"id":51226018,"url":"https://github.com/pitill0/ctxcuts","last_synced_at":"2026-06-28T11:31:15.871Z","repository":{"id":367772189,"uuid":"1282230779","full_name":"pitill0/ctxcuts","owner":"pitill0","description":"Portable context shortcuts for AI agent workflows.","archived":false,"fork":false,"pushed_at":"2026-06-27T15:35:15.000Z","size":164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T16:15:58.379Z","etag":null,"topics":["agent-tools","agents","ai","cli","context","developer-tools","llm","prompt-engineering","python","shortcuts"],"latest_commit_sha":null,"homepage":"","language":"Python","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/pitill0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"ROADMAP.md","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-06-27T13:51:24.000Z","updated_at":"2026-06-27T15:35:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pitill0/ctxcuts","commit_stats":null,"previous_names":["pitill0/ctxcuts"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/pitill0/ctxcuts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitill0%2Fctxcuts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitill0%2Fctxcuts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitill0%2Fctxcuts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitill0%2Fctxcuts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pitill0","download_url":"https://codeload.github.com/pitill0/ctxcuts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pitill0%2Fctxcuts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34887328,"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-28T02:00:05.809Z","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":["agent-tools","agents","ai","cli","context","developer-tools","llm","prompt-engineering","python","shortcuts"],"created_at":"2026-06-28T11:31:15.192Z","updated_at":"2026-06-28T11:31:15.862Z","avatar_url":"https://github.com/pitill0.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ctxcuts\n\nPortable context shortcuts for AI agent workflows.\n\n`ctxcuts` is a tiny CLI for defining reusable context shortcuts like `:r`,\n`:f`, `:s` or `:a` and expanding them into focused prompts for coding agents,\nchat assistants, CLIs and custom workflows.\n\nThe goal is simple: stop repeating long prompts, avoid oversized always-on\ncontext, and load only the task contract you need when you need it.\n\nThink of it as an `.editorconfig` for agent context: small, local-first,\nversionable and vendor-neutral.\n\n## Tiny example\n\n```bash\nctxc expand \":r src/player.py\"\nctxc expand \":s src/auth.py --focus input-validation\"\nctxc expand \":i web player stops after switching stations\"\n```\n\n## Why?\n\nBefore:\n\n```text\nPlease investigate why the web player sometimes stops after switching stations.\nDo not patch anything yet. Look for lifecycle problems, race conditions and\nbrowser audio edge cases. Give me likely causes first.\n```\n\nAfter:\n\n```text\n:i web player stops after switching stations --focus lifecycle\n```\n\n`ctxcuts` expands that tiny instruction into a reusable context contract.\n\n## See the context gain\n\n`ctxc stats` gives a lightweight estimate of how much reusable context is being\nloaded from a tiny shortcut invocation.\n\n```bash\nctxc stats \":r src/ctxcuts/cli.py\"\n```\n\nExample output:\n\n```text\n           ctxcuts stats\n┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓\n┃ Metric                   ┃ Value ┃\n┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩\n│ Shortcut input tokens    │     7 │\n│ Expanded prompt tokens   │   113 │\n│ Reusable context tokens  │   106 │\n│ Typed portion            │    6% │\n│ Reusable context portion │   94% │\n│ Context budget           │   800 │\n│ Budget used              │   14% │\n└──────────────────────────┴───────┘\n```\n\nThe estimate is intentionally simple. It is not a provider-specific billing\ncalculator. The useful signal is that most of the prompt comes from reusable,\nversioned context instead of repeated manual typing.\n\n## Install for local development\n\nThis project is designed for `uv`, but it uses a standard `pyproject.toml`.\n\n```bash\nuv sync\nuv run ctxc --help\n```\n\nWithout `uv`, any modern Python workflow that understands `pyproject.toml` should\nwork.\n\n## Quick start\n\nCreate default context shortcuts in your repo:\n\n```bash\nctxc init\n```\n\nList available shortcuts:\n\n```bash\nctxc list\n```\n\nExpand a shortcut:\n\n```bash\nctxc expand \":r src/app.py\"\n```\n\nCopy an expanded prompt to the clipboard:\n\n```bash\nctxc copy \":r src/app.py --focus security --var area=auth\"\n```\n\n`copy` expands the invocation exactly like `ctxc expand`, then writes the expanded\nprompt to your system clipboard.\n\nValidate a `.ctxcuts/` setup:\n\n```bash\nctxc doctor\nctxc doctor --root examples/basic\n```\n\n`doctor` reports missing context files as errors and suspicious context issues\nas warnings.\n\nShow a shortcut context without expanding a full invocation:\n\n```bash\nctxc show :r\nctxc show review\nctxc show --root examples/basic :s\n```\n\nEstimate token-ish savings:\n\n```bash\nctxc stats \":r src/app.py\"\n```\n\nPipe into another tool:\n\n```bash\nctxc expand \":r src/app.py\" | codex\nctxc expand \":r src/app.py\" | claude\nctxc expand \":r src/app.py\" | aider\n```\n\n## Working from another root\n\nUse `--root` when the `.ctxcuts/` directory lives somewhere else.\n\n```bash\nctxc list --root examples/basic\nctxc expand --root examples/basic \":r src/app.py\"\nctxc stats --root examples/basic \":r src/app.py\"\n```\n\nThis is useful for examples, monorepos, wrapper scripts and tools that invoke\n`ctxc` from a different working directory.\n\n## Default shortcuts\n\n| Shortcut | Name | Purpose |\n| --- | --- | --- |\n| `:r` | review | Review without editing |\n| `:f` | fix | Fix a concrete issue with the smallest safe change |\n| `:t` | tests | Work on tests, failures and regressions |\n| `:d` | docs | Improve or generate documentation |\n| `:s` | security | Look for security issues and unsafe assumptions |\n| `:a` | audit | Perform a structured audit |\n| `:q` | quality | Improve maintainability and long-term quality |\n| `:p` | perf | Analyze performance, latency and bottlenecks |\n| `:x` | explain | Explain before changing anything |\n| `:m` | map | Build a compact map of a file, module or repo area |\n| `:i` | investigate | Investigate an issue before proposing a fix |\n| `:c` | commit | Prepare commit summary, diff review or changelog entry |\n\n## Template variables\n\nContext files can use tiny built-in placeholders:\n\n```markdown\nTarget: {{ target }}\nFocus: {{ focus | default: \"bugs, regressions and edge cases\" }}\nOutput: {{ output | default: \"summary + findings + recommendation\" }}\n```\n\nThen pass values from the shortcut invocation:\n\n```bash\nctxc expand \":r src/app.py --focus security --output checklist\"\n```\n\nSupported variables include:\n\n| Variable | Meaning |\n| --- | --- |\n| `target` | Free-form target text after the shortcut |\n| `focus` | Value passed with `--focus` |\n| `output` | Value passed with `--output`, or the configured default output |\n| `mode` | Shortcut mode from `shortcuts.yml` |\n| `shortcut` | Shortcut name from `shortcuts.yml` |\n\nPass generic variables into a context:\n\n```bash\nctxc expand \":r src/app.py --var area=auth --var risk=high\"\n```\n\nThen use them in context files:\n\n```markdown\nArea: {{ area | default: \"general\" }}\nRisk: {{ risk | default: \"unknown\" }}\n```\n\nGeneric variable names must start with a letter or underscore and may contain\nletters, numbers and underscores. Built-in variables such as `target`, `focus`,\n`output`, `mode` and `shortcut` cannot be overridden with `--var`.\n\nThe renderer is intentionally tiny and dependency-free. It supports\n`{{ name }}` and `{{ name | default: \"value\" }}`. It is not Jinja.\n\n## Config layout\n\n```text\n.ctxcuts/\n├── shortcuts.yml\n└── contexts/\n    ├── review.md\n    ├── fix.md\n    ├── tests.md\n    ├── docs.md\n    ├── security.md\n    ├── audit.md\n    ├── quality.md\n    ├── perf.md\n    ├── explain.md\n    ├── map.md\n    ├── investigate.md\n    └── commit.md\n```\n\n## Example config\n\n```yaml\nversion: 1\n\ndefaults:\n  prefix: \":\"\n  output: markdown\n  token_budget: 800\n\nshortcuts:\n  r:\n    name: review\n    context: contexts/review.md\n    description: Review code or text without modifying it.\n    mode: read_only\n```\n\n## What ctxcuts saves\n\n`ctxcuts` is designed to reduce:\n\n- repeated typing\n- duplicated prompt boilerplate\n- oversized always-on context files\n- copy/paste drift between team members\n- unclear agent task modes\n\nIt does not promise:\n\n- exact model-specific token counts\n- automatic billing reduction in every provider\n- autonomous agent orchestration\n- embeddings, memory or vector search\n- vendor-specific agent behavior\n\nIf your tool sends the fully expanded prompt to a model, those tokens still\nexist. `ctxcuts` helps you keep that context focused, reusable and explicit.\nProvider-side caching or external context loading can produce additional\nsavings, depending on the stack.\n\n## Continuous integration\n\nThe repository includes CI workflows for both Gitea Actions and GitHub Actions:\n\n```text\n.gitea/workflows/ci.yml\n.github/workflows/ci.yml\n```\n\nBoth workflows run the same checks:\n\n```bash\nuv run ruff format --check .\nuv run ruff check .\nuv run pytest\nuv run mypy src\nuv build\n```\n\n## Philosophy\n\n`ctxcuts` is not an agent framework.\n\nIt is closer to an `.editorconfig` for agent context:\n\n- small\n- local-first\n- portable\n- versionable\n- vendor-neutral\n- easy to delete\n\nShortcuts are not magic commands. They are portable context contracts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitill0%2Fctxcuts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpitill0%2Fctxcuts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpitill0%2Fctxcuts/lists"}