Jctx is a command-line tool used to convert Java, Kotlin, or Python projects into AI-readable context files. Its core purpose is to solve the problem that developers need to manually copy and paste large amounts of code and explain class structures when asking AI questions. With a single command, it generates a context.txt or context.md file containing complete project architecture information, enabling AI to give precise answers based on the real code structure.
Main capabilities:
- Project scanning and extraction: Automatically scans every class, field, method signature, Javadoc/KDoc/docstring comment, and build file in the project, and outputs a clean, structured context file.
- Output formats: Supports generating context.txt or context.md, making it convenient to paste directly into an AI chat.
- Analysis metrics: After generating the file, an analysis dashboard is printed to the console, including language proportions (showing the proportions of Java, Kotlin, and Python by lines of code), dependency graph (mapping dependencies between classes within the project, based on import statements and in-body type references, showing only project-internal references), and token count estimation (breaking down the total token count by section and checking whether it fits within the context windows of mainstream AI models).
- Custom exclusion: Supports placing a .jctxignore file in the project root directory to exclude additional directories or files; by default, build artifacts such as build/, target/, .idea/, .git/, node_modules/, .gradle/, .class, .jar, etc. are automatically ignored.
- GitHub Actions integration: Provides a ready-made workflow that can automatically generate a context report on every push or pull request, upload the generated context.md or context.txt as a workflow artifact (retained for 30 days), and comment a report preview on the PR; subsequent pushes update the existing comment. Repository variables can control whether the report is committed back to the repository, with the commit message being chore: update Jctx context report [skip ci], and contents: write permission must be added to the workflow. It also supports direct use of a composite action for modular integration.
How to use:
- Installation: It is recommended to install via PyPI using pip. After installation, jctx can be used directly in the terminal.On Windows, the manual method is to download the latest release zip, right-click Setup.bat and run it as administrator, then open a new terminal; if you do not have administrator privileges, you can copy jctx.py and jctx.bat to any location and run jctx.bat directly; on non-Windows systems, you can run python jctx.py "path/to/project" in a Python 3.8+ environment.
- Usage output: Paste context.txt (or the contents of context.md) into any AI chat, then ask a question, for example, "This is my Java/Kotlin/Python project structure: [paste]. I want to refactor the messaging module to use WebSockets—where should I start?" The output is suitable for Claude, ChatGPT, Gemini, and other AIs that accept long text input.
- Environment requirements: Python 3.8 or later, supporting Windows, macOS, and Linux.
Use cases:
- When you need to quickly provide complete project context before asking an AI, avoiding manual copy-pasting.
- When you need to understand the project's language proportions, dependencies, or estimate token counts to fit AI context windows.
- When you want to automatically generate and track project context reports in a CI/CD process.
Limitations and notes:
- The tool is mainly aimed at Java, Kotlin, and Python projects; support for other languages is not currently provided.
- Pricing, costs, and specific platform effects are not explained in the materials and are not currently provided.
- It scans only internal project dependencies and does not include external library references.
- Some features such as clipboard support, Slim mode, and architecture diagram generation (--diagram) are listed as planned or mentioned in the materials, but specific usage details and availability are not currently provided.
- The license is MIT, free to use, modify, and share.
