{"id":48904638,"url":"https://github.com/Shashwat-Gupta57/jctx","last_synced_at":"2026-05-02T20:00:35.349Z","repository":{"id":347580422,"uuid":"1194545869","full_name":"Shashwat-Gupta57/Jctx","owner":"Shashwat-Gupta57","description":"Turn any Java or Kotlin project into an AI-ready context file in one command.","archived":false,"fork":false,"pushed_at":"2026-04-17T04:51:56.000Z","size":788,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T06:33:51.624Z","etag":null,"topics":["ai","chatgpt","claude","claude-code","cli","code-analysis","context","developer-tools","java","kotlin","markdown","productivity","python","static-analysis"],"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/Shashwat-Gupta57.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-03-28T14:00:10.000Z","updated_at":"2026-04-17T04:51:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Shashwat-Gupta57/Jctx","commit_stats":null,"previous_names":["shashwat-gupta57/jmap"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Shashwat-Gupta57/Jctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shashwat-Gupta57%2FJctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shashwat-Gupta57%2FJctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shashwat-Gupta57%2FJctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shashwat-Gupta57%2FJctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shashwat-Gupta57","download_url":"https://codeload.github.com/Shashwat-Gupta57/Jctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shashwat-Gupta57%2FJctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32547651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T19:18:06.202Z","status":"ssl_error","status_checked_at":"2026-05-02T19:16:21.335Z","response_time":132,"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":["ai","chatgpt","claude","claude-code","cli","code-analysis","context","developer-tools","java","kotlin","markdown","productivity","python","static-analysis"],"created_at":"2026-04-16T19:00:43.475Z","updated_at":"2026-05-02T20:00:35.342Z","avatar_url":"https://github.com/Shashwat-Gupta57.png","language":"Python","funding_links":[],"categories":["Projects"],"sub_categories":["Utility"],"readme":"![Demo GIF](./JctxSample-1.8.0.gif)\n# Jctx — Give AI full understanding of your Java, Kotlin \u0026 Python codebase\n\n**Stop pasting files. Get real architecture-aware answers.**\n\n**Generate complete project context in seconds.**\n\n**Turn any Java, Kotlin, or Python project into a single AI-ready `context.txt` (or `context.md`) in seconds.**\n\n```\nJctx \"C:\\projects\\MyApp\"\n→  context.txt written  (Java: 39 files | Kotlin: 12 files | Python: 15 files | POM: 1 file | Gradle: 1 file)\n```\n\nNo config. No dependencies. Just Python and a folder.\n\n---\n\n## Why it exists\n\nYou're working on a Java, Kotlin, or Python project. You open an AI chat to get help. Before you can even ask your question, you spend 10 minutes copy-pasting files, explaining your class structure, summarising what each module does.\n\n**Before:**\nChatGPT suggests random classes\n\n**After:**\nChatGPT tells exactly which class to modify and why\n\n**Jctx does all of that in one command.**\n\nIt scans your project and writes a clean, structured `context.txt` (or `context.md`) — every class, every field, every method signature, every Javadoc/KDoc/docstring comment, and your build files — formatted so an AI can immediately understand your entire codebase.\n\nIt also provides **Token Count Estimation**, **Language Percentages**, and a **Dependency Graph** — all printed to your console automatically.\n\nPaste it. Ask your question. Get useful answers.\n\n---\n\n## Output (real example)\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand sample context.txt (Plain Text - Default)\u003c/summary\u003e\n\n```text\n================================================================\n JCTX v2.1.0 - Java, Kotlin \u0026 Python Context Extractor\n Project : C:\\projects\\Talken\n Date    : 2026-03-31 12:00:00\n Files   : Java: 39 file(s) | Kotlin: 5 file(s) | Python: 2 file(s) | POM: 1 file(s) | Gradle: 1 file(s)\n================================================================\n\n================================================================\n SECTION 1 - PROJECT FILE TREE\n================================================================\n\n  Talken\\\n  ├── src\\\n  │   └── main\\\n  │       ├── java\\\n  │       │   └── org\\\n  │       │       └── flexstudios\\\n  │       │           └── talken\\\n  │       │               ├── Controls.java\n  │       │               └── TalkenClient.java\n  │       └── kotlin\\\n  │           └── org\\\n  │               └── flexstudios\\\n  │                   └── talken\\\n  │                       └── UserProfile.kt\n  ├── build.gradle\n  └── pom.xml\n\n================================================================\n SECTION 2 - POM.XML CONTENT\n================================================================\n\n----------------------------------------------------------------\n  FILE: pom.xml\n----------------------------------------------------------------\n\n  \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n  \u003cproject\u003e\n      \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n      \u003cgroupId\u003eorg.flexstudios\u003c/groupId\u003e\n      \u003cartifactId\u003etalken\u003c/artifactId\u003e\n      \u003cversion\u003e1.0.0\u003c/version\u003e\n  \u003c/project\u003e\n\n================================================================\n SECTION 3 - KOTLIN CLASS AND MEMBER DETAILS\n================================================================\n\n----------------------------------------------------------------\n  FILE: src\\main\\kotlin\\org\\flexstudios\\talken\\UserProfile.kt\n----------------------------------------------------------------\n\n  CLASS: UserProfile\n  DOC  : Represents the user's local profile settings.\n\n  DATA MEMBERS:\n    · private val String displayName\n    · private val String email\n\n  METHODS:\n    [1] String getAboutSection()\n         DOC: (no documentation)\n\n================================================================\n END OF REPORT\n================================================================\n```\n\n\u003c/details\u003e\n\n---\n\n## Install\n\n**Option 1: PyPI (Recommended)**\nThe easiest way to install Jctx on any OS (Windows, macOS, Linux) is via pip:\n```bash\npip install jctx\n```\nThe `jctx` command will be instantly available in your terminal.\n\n**Option 2: Manual Download (Windows)**\n1. Download The Latest **Release** Zip.\n2. Unzip it\n3. Right-click `Setup.bat` → **Run as administrator**\n4. Open a new terminal\n\n```bat\njctx \"C:\\path\\to\\your\\java\\project\"\n```\n\n\u003e **No admin rights?** Copy `jctx.py` + `jctx.bat` anywhere and run `jctx.bat` directly.\n\n\u003e **Not on Windows?** Run `python jctx.py \"path/to/project\"` on any OS with Python 3.8+.\n\n---\n\n## Usage\n\n```\nJctx \u003cproject_folder\u003e [--md] [--slim] [--no-tree] [--clipboard] [--print] [--version] [--help]\n```\n\n| Flag | Effect |\n|---|---|\n| *(none)* | Saves `context.txt` into your project folder and prints token estimates |\n| `--md` | Outputs a cleanly formatted Markdown file (`context.md`) instead of plain text |\n| `--slim` | Slim mode: output only class names and method signatures (omits fields and docs) to save tokens |\n| `--no-tree` | Skips the file tree section (shorter output) |\n| `--clipboard` | Copies the generated report directly to your clipboard |\n| `--print` | Also prints to the console |\n| `--version` | Shows the Jctx version |\n| `--help` | Shows help |\n\n---\n\n## How to use the output\n\nPaste `context.txt` (or the contents of `context.md`) into any AI chat and ask your question:\n\n\u003e *\"Here's my Java/Kotlin/Python project structure: [paste]. I want to refactor the messaging module to use WebSockets — where should I start?\"*\n\nWorks great with **Claude**, **ChatGPT**, **Gemini**, and any other AI that accepts long text input.\n\n---\n\n## Console Metrics\n\nAfter generating the file, Jctx prints a full analytics dashboard to your console:\n\n### Language Percentages\n\nShows the exact split of Java vs Kotlin vs Python code by lines of code:\n\n```text\n================================================================\n LANGUAGE PERCENTAGES\n================================================================\n  Java    :  60.2%  ██████████████████████████████░░░░░░░░░░░░░░░░░░░░  (4,120 lines)\n  Kotlin  :  28.1%  ██████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  (1,920 lines)\n  Python  :  11.7%  █████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  (800 lines)\n================================================================\n```\n\n### Dependency Graph\n\nAutomatically maps which of your project classes depend on which — scans both import statements and in-body type references (catches same-package dependencies too). Only shows project-internal references, no external library noise:\n\n```text\n================================================================\n DEPENDENCY GRAPH (project-internal)\n================================================================\n  EncryptionModule → (none)\n  MessagingModule → EncryptionModule, UserProfile\n  TalkenClient → EncryptionModule, MessagingModule, UserProfile\n  UserProfile → (none)\n================================================================\n```\n\n### Token Count Estimate\n\nShows the total token count with a breakdown by section and checks whether your context fits each major AI model's context window:\n\n```text\n================================================================\n TOKEN ESTIMATE\n================================================================\n  Total tokens : ~34,767\n\n  Language Breakdown:\n    Java        : ~  23,400  ( 59.3%)\n    Kotlin      : ~  10,910  ( 27.6%)\n    Python      : ~   4,560  ( 11.6%)\n    Build files : ~     290  (  0.7%)\n    File tree   : ~     312  (  0.8%)\n\n  Context Window Fit:\n    Y Llama 4 Scout (10M)      Y Gemini 3.1 (2M)          Y Grok (2M)\n    Y GPT-5.4 (1M)             Y Claude 4.6 (1M)          Y Qwen 3 (1M)\n================================================================\n```\n\n---\n\n## `.jctxignore` — Custom Exclusions\n\nPlace a `.jctxignore` file in the project root to exclude additional directories or files from context extraction:\n\n```gitignore\n# Skip test directories\n**/test/**\n\n# Skip generated code\ngenerated/\n\n# Skip specific file patterns\n*.test.java\n```\n\n| Pattern | Meaning |\n|---------|---------|\n| `dirname/` | Skip any directory named `dirname` |\n| `**/test/**` | Skip any directory named `test` anywhere in the tree |\n| `*.test.java` | Skip files matching the glob pattern |\n| `# comment` | Lines starting with `#` are ignored |\n\nWhen a `.jctxignore` is detected, the console banner shows:\n```\n  .jctxignore: yes (2 dirs, 1 patterns)\n```\n\n---\n\n## What it extracts\n\n| What | Detail |\n|---|---|\n| File tree | Full project structure, build folders excluded |\n| Build Files | Full content of your `pom.xml`, `build.gradle`, `requirements.txt`, and `pyproject.toml` |\n| Classes | Java/Kotlin classes and interfaces, Python classes, plus all docstrings/JavaDocs/KDocs |\n| Fields | Type, name, access modifier, val/var (Kotlin), instance vars (`self.x`), inline comments |\n| Methods | Numbered list — return type, name, params, decorators, top-level Python/Kotlin functions |\n\n**Auto-ignored:** `build/`, `target/`, `.idea/`, `.git/`, `node_modules/`, `.gradle/`, `.class`, `.jar`, and all other build artifacts. Customize further with `.jctxignore`.\n\n---\n\n## Requirements\n\n- Python 3.8 or newer — [python.org](https://python.org)\n- Works on Windows, macOS, Linux\n\n---\n\n## GitHub Actions — Automatic Context Reports\n\nJctx ships with a ready-made GitHub Actions workflow that automatically generates a context report on every push or pull request, saving you from running the tool manually.\n\n### What the workflow does\n\n1. **Checks out** your repository.\n2. **Installs Jctx** from PyPI (with pip caching so repeated runs are fast).\n3. **Runs `jctx`** on your project and prints the analytics dashboard to the Actions log.\n4. **Uploads** the generated `context.md` (or `context.txt`) as a downloadable workflow artifact (retained for 30 days).\n5. **Comments** a preview of the report on the pull request (when triggered by `pull_request`). Subsequent pushes to the same PR update the existing comment instead of creating a new one.\n6. **Optionally commits** the report back to the repository (disabled by default; see configuration below).\n\n---\n\n### Quick start — copy the workflow into your own repository\n\n```bash\n# From the root of your repository:\nmkdir -p .github/workflows\ncurl -o .github/workflows/jctx-context-report.yml \\\n  https://raw.githubusercontent.com/Shashwat-Gupta57/Jctx/main/.github/workflows/jctx-context-report.yml\n```\n\nThen commit and push. The workflow will run on your next push.\n\n---\n\n### Configuration\n\nAll options are controlled via **repository variables** (Settings → Secrets and variables → Variables → New repository variable). No workflow file edits are needed.\n\n| Variable | Default | Description |\n|---|---|---|\n| `JCTX_PROJECT_PATH` | `.` | Path to the project folder to analyse, relative to the repo root. Example: `./my-java-app` |\n| `JCTX_OUTPUT_FORMAT` | `md` | Output format: `md` (Markdown) or `txt` (plain text). |\n| `JCTX_SLIM_MODE` | `false` | Set to `true` to use slim mode (class names + method signatures only). |\n| `JCTX_NO_TREE` | `false` | Set to `true` to omit the file-tree section. |\n| `JCTX_COMMIT_REPORT` | `false` | Set to `true` to automatically commit the report back to the repo (see below). |\n| `JCTX_COMMIT_PATH` | `docs/context-report` | Folder where the committed report is stored (only used when `JCTX_COMMIT_REPORT=true`). |\n\n#### Committing the report back to the repository\n\nTo enable automatic commits of the generated report:\n\n1. Set the repository variable `JCTX_COMMIT_REPORT` to `true`.\n2. Add `contents: write` to the workflow permissions (edit the `permissions:` block in the workflow file):\n\n```yaml\npermissions:\n  contents: write        # needed to commit the report\n  pull-requests: write   # needed for PR comments\n```\n\nThe commit message is `chore: update Jctx context report [skip ci]` (the `[skip ci]` tag prevents the commit from triggering another workflow run).\n\n#### Required permissions\n\n| Feature | Permission needed |\n|---|---|\n| Artifact upload | *(none — included by default)* |\n| PR comment | `pull-requests: write` *(already set in the workflow)* |\n| Commit report | `contents: write` *(must be added manually if you enable `JCTX_COMMIT_REPORT`)* |\n\n---\n\n### Using the reusable composite action\n\nIf you prefer a more modular approach, use the composite action directly in your own workflow:\n\n```yaml\njobs:\n  context:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Generate Jctx context report\n        id: jctx\n        uses: Shashwat-Gupta57/Jctx/.github/actions/generate-context@main\n        with:\n          project-path: '.'        # folder to analyse\n          output-format: 'md'      # 'md' or 'txt'\n          slim: 'false'            # 'true' for slim mode\n          no-tree: 'false'         # 'true' to skip file tree\n          # jctx-version: '2.1.0' # pin a specific version (optional)\n\n      - name: Upload report\n        uses: actions/upload-artifact@v4\n        with:\n          name: context-report\n          path: ${{ steps.jctx.outputs.report-path }}\n```\n\n**Action inputs**\n\n| Input | Default | Description |\n|---|---|---|\n| `project-path` | `.` | Project folder to analyse. |\n| `output-format` | `md` | `md` or `txt`. |\n| `slim` | `false` | Slim mode (class names + signatures only). |\n| `no-tree` | `false` | Omit file-tree section. |\n| `jctx-version` | *(latest)* | Pin a specific PyPI version of jctx. |\n\n**Action outputs**\n\n| Output | Description |\n|---|---|\n| `report-path` | Path to the generated report file inside the runner workspace. |\n\n---\n\n### More GitHub Actions ideas\n\nHere are additional ways to integrate Jctx (and GitHub Actions in general) to make your workflow even more powerful:\n\n| Idea | How |\n|---|---|\n| **Scheduled context snapshots** | Add a `schedule` trigger (see example below the table) to generate a weekly context report automatically. |\n| **Publish to GitHub Pages** | Use `actions/deploy-pages` to host the latest `context.md` as a browsable site for the project. |\n| **Generate a changelog** | Combine Jctx with tools like [`git-cliff`](https://github.com/orhun/git-cliff) or [`release-drafter`](https://github.com/release-drafter/release-drafter) to auto-create changelogs on release. |\n| **Release automation** | Trigger a release workflow on version-tag pushes (`v*`) that publishes to PyPI or GitHub Releases and attaches the context report as a release asset. |\n| **PR labeling** | Use `actions/labeler` to automatically label PRs based on which files changed (e.g., `java`, `kotlin`, `python`). |\n| **Security scanning** | Add `github/codeql-action` to scan your Java/Kotlin/Python source files for vulnerabilities on every push. |\n| **Dependency review** | Use `actions/dependency-review-action` on PRs to catch newly introduced vulnerable dependencies. |\n| **Issue/PR templates validation** | Enforce PR descriptions with a custom action that checks the PR body against a template. |\n| **Stale issue management** | Use `actions/stale` to automatically close issues and PRs that have been inactive for a configurable number of days. |\n| **Notify on Slack/Discord** | Send a webhook notification with a link to the generated context report artifact after each run. |\n| **Matrix builds** | Run Jctx across multiple project sub-folders in a single workflow using a matrix strategy. |\n\nExample — weekly scheduled run (add to the `on:` block of the workflow):\n\n```yaml\non:\n  schedule:\n    - cron: '0 0 * * 1'   # every Monday at midnight UTC\n  push:\n    branches: ['**']\n  workflow_dispatch:\n```\n\n---\n\n## Roadmap\n\n- [x] Kotlin support\n- [x] Markdown output mode (`context.md`)\n- [x] Multi-language project estimations (mixed Java + Kotlin percentages)\n- [x] Token count estimate alongside output\n- [x] Clipboard support and Slim mode\n- [x] Dependency graph (project-internal)\n- [x] `.jctxignore` custom exclusions\n- [x] Cross-platform packaging (PyPI / pip)\n- [x] Python language support\n- [ ] Architecture diagram generation (`--diagram`)\n\n---\n\n## License\n\nMIT — free to use, modify, and share.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShashwat-Gupta57%2Fjctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FShashwat-Gupta57%2Fjctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FShashwat-Gupta57%2Fjctx/lists"}