pycodectx 1.0.2

Project context extraction tool for code analysis and AI workflows

CodeCtx

CodeCtx scans a project directory and writes a project.ctx.json file with high-signal context that is useful for AI workflows, code reviews, onboarding, and lightweight documentation.

What it does

• Scans a target directory and builds a project context snapshot.
• Extracts file structure, functions, APIs, dependencies, environment hints, summaries, and plugin output.
• Writes the result into the directory where you run the command.
• Keeps a single rolling backup in project.ctx.json.backup.
• Auto-initializes its config directory on first run.

Installation

Setup

Use the single supported setup command:

codectx-setup

It:

• deploys or refreshes the app under the standard tool directory
• creates venv/ if needed
• installs runtime dependencies from requirements.txt
• generates launchers in bin/
• prefers a user launcher directory already on PATH, such as ~/.local/bin
• attempts to update PATH when necessary

Default deployment targets:

• Windows: C:\tools\codectx
• macOS / Linux: ~/tools/codectx

You can override the destination:

codectx-setup --target /custom/path/codectx

Option 2: standard Python install

pip install .

After publishing to PyPI:

pip install pycodectx

For local development:

pip install -e .

The published package name is pycodectx, but the installed CLI command remains codectx, and setup remains codectx-setup.

Publishing

Build locally:

python -m pip install --upgrade pip build
python -m build

The repository includes a GitHub Actions workflow at .github/workflows/release.yml that:

• builds the source distribution and wheel
• publishes to PyPI using Trusted Publishing
• runs when you push a tag like v1.0.0

Typical release flow:

git tag vX.Y.Z
git push origin vX.Y.Z

Before the first release, configure a PyPI Trusted Publisher for project pycodectx and point it at .github/workflows/release.yml.

Usage

# Analyze the current directory
codectx .

# Analyze a specific project
codectx /path/to/project

# Show extra detail
codectx . --verbose

# Plugin management
codectx plugin list
codectx plugin add /path/to/plugin.py
codectx plugin remove my_plugin

Output behavior

• project.ctx.json is written into the directory you analyze.
• If that file already exists, CodeCtx copies the previous version to project.ctx.json.backup.
• Only the latest backup is kept.

Configuration

CodeCtx stores configuration in a per-user directory by default:

• Windows: %LOCALAPPDATA%\CodeCtx
• macOS: ~/.config/codectx
• Linux: ~/.config/codectx

To override that location, set CODECTX_CONFIG_DIR.

Example:

CODECTX_CONFIG_DIR=/custom/path/codectx

The generated config.json controls values such as:

• output_file
• ignore_dirs
• ignore_files
• plugins_enabled
• auto_backup

Project layout

codectx/
  src/codectx/   Python package
  bin/           generated launchers
  venv/          local virtual environment created by bootstrap
  bootstrap.py   cross-platform setup entry

License

CodeCtx is released under the MIT License. See LICENSE.

Support

• Repository: https://github.com/prathmesh284/codectx
• Issues: https://github.com/prathmesh284/codectx/issues