# CodeSum: AI-Powered Code Summarizer with TUI 🐍📄✨
**Generate concise code summaries optimized for Large Language Models (LLMs) using an interactive Text User Interface (TUI).**
This tool analyzes your project structure, lets you select relevant files through an interactive TUI, and generates summaries tailored for AI interaction. It can create both a full-content summary (copied to your clipboard) and an AI-powered compressed summary, leveraging models like GPT-4o via the OpenAI API. Features include intelligent summary caching, `.gitignore` respect, and optional AI-driven README generation based on the compressed summary.
## Model Context Protocol (MCP) Server 🌐
CodeSum now includes an MCP (Model Context Protocol) server that allows other AI tools to interact with your codebase programmatically. The MCP server can intelligently select relevant files based on a query and return structured summaries that can be used as context for LLM interactions.
## Video Tutorial (Demonstrates Core Functionality)
[](https://www.youtube.com/watch?v=IY-KIMyUaB8)
*(Note: The video might show older setup steps, but the core TUI and summarization process remains similar.)*
## Key Features 🔑
* **Interactive TUI:** Uses `curses` for a smooth file selection experience directly in your terminal.
* **Smart Selection:** Remembers your previously selected files for the project.
* **Respects `.gitignore`:** Automatically excludes files and directories listed in your `.gitignore`.
* **Configurable Ignores:** Uses a default list of common ignores (like `.git`, `venv`, `node_modules`) in addition to `.gitignore`.
* **Dual Summaries:**
* **Local Summary:** Creates a `code_summary.md` with the full content of selected files and project structure (automatically copied to clipboard).
* **AI Compressed Summary:** (Optional) Generates a `compressed_code_summary.md` using an LLM for concise summaries of each file, ideal for large context windows.
* **Intelligent Caching:** AI summaries are cached based on file content hashes, avoiding redundant API calls for unchanged files.
* **AI README Generation:** (Optional) Updates or creates a `README.md` in your project root using the AI-generated compressed summary.
* **Easy Configuration:** Manage your OpenAI API key and preferred model via a simple command (`codesum --configure`) or during the first run. Configuration is stored securely in your user config directory.
* **Cross-Platform:** Works on Linux, macOS, and Windows (includes necessary `windows-curses` dependency).
* **PyPI Package:** Easily installable via `pip`.
## Installation 🛠️
Requires Python 3.8 or higher.
### Option 1: From PyPI (Recommended)
This is the standard and recommended way to install `CodeSum`:
```sh
pip install codesum
```
This command downloads the package from the Python Package Index (PyPI) and installs it along with its dependencies. The codesum command will then be available in your environment.
Option 2: From Source (for Development or Latest Version)
If you want to install directly from the source code (e.g., for development or to get the absolute latest changes not yet released on PyPI):
Clone the repository:
```sh
git clone https://github.com/sam1am/codesum.git
cd codesum
```
Create and activate a virtual environment (highly recommended):
```sh
python3 -m venv venv
source venv/bin/activate # On Windows use `.\venv\Scripts\activate`
```
Install the package:
For a regular install from source:
```sh
pip install .
```
For an editable install (changes in the source code are reflected immediately):
```sh
pip install -e .
```
Configuration
CodeSum needs your OpenAI API key to use AI features.
Run the configuration wizard after installation:
```sh
codesum --configure
```
This will interactively prompt you for your OpenAI API Key and the desired LLM model (e.g., gpt-4o).
Alternatively, the tool will prompt you for the API key on the first run if it's not already configured.
Configuration is saved in a settings.env file within your user's config directory (e.g., ~/.config/codesum on Linux, ~/Library/Application Support/codesum on macOS, %APPDATA%\codesum\codesum on Windows). You can leave the API key blank if you only want to use the local summary and clipboard features.
## Usage 🚀
Navigate to your project's root directory in your terminal.
Run the command:
```sh
codesum
```
The interactive TUI will launch, allowing you to select files using the arrow keys and spacebar.
[SPACE] : Toggle selection for the highlighted file.
[↑↓] : Navigate up/down.
[←→ / PgUp / PgDn] : Navigate pages.
[ENTER] : Confirm selection and proceed.
[Q / ESC] : Quit without saving changes.
After confirming your selection, the tool will:
Create/update .summary_files/code_summary.md.
Copy the content of code_summary.md to your clipboard.
Save your selection in .summary_files/previous_selection.json.
If an OpenAI API key is configured:
It will ask if you want to generate an AI-powered compressed summary (.summary_files/compressed_code_summary.md).
If the compressed summary is generated, it will ask if you want to generate/update the root README.md file based on it.
## MCP Server Usage 🌐
CodeSum includes an MCP (Model Context Protocol) server that can be used by other AI tools to interact with your codebase programmatically.
To start the MCP server:
```sh
codesum --mcp-server
```
By default, the server will run on `localhost:8000`. You can specify a different host and port:
```sh
codesum --mcp-server --mcp-host 0.0.0.0 --mcp-port 8001
```
The MCP server provides the following endpoints:
- `GET /health` - Health check endpoint
- `GET /summarize?query=<query>&max_files=<N>` - Generate summary with query parameters
- `POST /summarize` - Generate summary with JSON body
See [MCP_USAGE.md](MCP_USAGE.md) for detailed API documentation and usage examples.
## Output 📂
## Output 📂
The tool creates a hidden .summary_files directory in your project root containing:
code_summary.md:
Contains the project structure tree and the full concatenated content of all selected files.
This content is automatically copied to your clipboard.
compressed_code_summary.md (Optional - requires API key):
Contains the project structure tree and AI-generated summaries for each selected file.
previous_selection.json:
Stores the absolute paths of the files you selected in the last run for this project.
[filename]_metadata.json (Optional - in subdirs matching source):
JSON files (one per AI-summarized file) storing the file's content hash and the generated AI summary for caching purposes.
Additionally, if you opt-in:
README.md (Optional - requires API key):
The project's main README file may be created or updated with AI-generated content based on the compressed summary.
And for configuration:
settings.env (Located in user config directory, not project dir):
Stores your OPENAI_API_KEY and LLM_MODEL.
## Dependencies 📚
Core dependencies (installed automatically via pip):
openai
pathspec
python-dotenv
pyperclip
platformdirs
windows-curses (on Windows only)
importlib-resources (on Python < 3.9 only)
## License 📜
This project is licensed under the MIT License.
## Acknowledgements 🙌
Thanks to the creators of the libraries used in this project and to everyone contributing to the open-source community.
Raw data
{
"_id": null,
"home_page": null,
"name": "codesum",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "code, summary, ai, openai, tui, curses, documentation",
"author": "Sam G",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/df/1b/1ed716e71461ae9629c43b62d940068d5004d1565d2ad9bf7743070ab6d6/codesum-0.2.12.tar.gz",
"platform": null,
"description": "# CodeSum: AI-Powered Code Summarizer with TUI \ud83d\udc0d\ud83d\udcc4\u2728\n\n**Generate concise code summaries optimized for Large Language Models (LLMs) using an interactive Text User Interface (TUI).**\n\nThis tool analyzes your project structure, lets you select relevant files through an interactive TUI, and generates summaries tailored for AI interaction. It can create both a full-content summary (copied to your clipboard) and an AI-powered compressed summary, leveraging models like GPT-4o via the OpenAI API. Features include intelligent summary caching, `.gitignore` respect, and optional AI-driven README generation based on the compressed summary.\n\n## Model Context Protocol (MCP) Server \ud83c\udf10\n\nCodeSum now includes an MCP (Model Context Protocol) server that allows other AI tools to interact with your codebase programmatically. The MCP server can intelligently select relevant files based on a query and return structured summaries that can be used as context for LLM interactions.\n\n## Video Tutorial (Demonstrates Core Functionality)\n\n[](https://www.youtube.com/watch?v=IY-KIMyUaB8)\n*(Note: The video might show older setup steps, but the core TUI and summarization process remains similar.)*\n\n## Key Features \ud83d\udd11\n\n* **Interactive TUI:** Uses `curses` for a smooth file selection experience directly in your terminal.\n* **Smart Selection:** Remembers your previously selected files for the project.\n* **Respects `.gitignore`:** Automatically excludes files and directories listed in your `.gitignore`.\n* **Configurable Ignores:** Uses a default list of common ignores (like `.git`, `venv`, `node_modules`) in addition to `.gitignore`.\n* **Dual Summaries:**\n * **Local Summary:** Creates a `code_summary.md` with the full content of selected files and project structure (automatically copied to clipboard).\n * **AI Compressed Summary:** (Optional) Generates a `compressed_code_summary.md` using an LLM for concise summaries of each file, ideal for large context windows.\n* **Intelligent Caching:** AI summaries are cached based on file content hashes, avoiding redundant API calls for unchanged files.\n* **AI README Generation:** (Optional) Updates or creates a `README.md` in your project root using the AI-generated compressed summary.\n* **Easy Configuration:** Manage your OpenAI API key and preferred model via a simple command (`codesum --configure`) or during the first run. Configuration is stored securely in your user config directory.\n* **Cross-Platform:** Works on Linux, macOS, and Windows (includes necessary `windows-curses` dependency).\n* **PyPI Package:** Easily installable via `pip`.\n\n## Installation \ud83d\udee0\ufe0f\n\nRequires Python 3.8 or higher.\n\n### Option 1: From PyPI (Recommended)\n\nThis is the standard and recommended way to install `CodeSum`:\n\n```sh\npip install codesum\n```\n\n\nThis command downloads the package from the Python Package Index (PyPI) and installs it along with its dependencies. The codesum command will then be available in your environment.\n\nOption 2: From Source (for Development or Latest Version)\n\nIf you want to install directly from the source code (e.g., for development or to get the absolute latest changes not yet released on PyPI):\n\nClone the repository:\n\n```sh\ngit clone https://github.com/sam1am/codesum.git\ncd codesum\n```\n\nCreate and activate a virtual environment (highly recommended):\n\n```sh\npython3 -m venv venv\nsource venv/bin/activate # On Windows use `.\\venv\\Scripts\\activate`\n```\n\nInstall the package:\n\nFor a regular install from source:\n\n```sh\npip install .\n```\n\nFor an editable install (changes in the source code are reflected immediately):\n\n```sh\npip install -e .\n```\n\nConfiguration\n\nCodeSum needs your OpenAI API key to use AI features.\n\nRun the configuration wizard after installation:\n\n```sh\ncodesum --configure\n```\n\nThis will interactively prompt you for your OpenAI API Key and the desired LLM model (e.g., gpt-4o).\n\nAlternatively, the tool will prompt you for the API key on the first run if it's not already configured.\n\nConfiguration is saved in a settings.env file within your user's config directory (e.g., ~/.config/codesum on Linux, ~/Library/Application Support/codesum on macOS, %APPDATA%\\codesum\\codesum on Windows). You can leave the API key blank if you only want to use the local summary and clipboard features.\n\n## Usage \ud83d\ude80\n\nNavigate to your project's root directory in your terminal.\n\nRun the command:\n\n```sh\ncodesum\n```\n\nThe interactive TUI will launch, allowing you to select files using the arrow keys and spacebar.\n\n[SPACE] : Toggle selection for the highlighted file.\n\n[\u2191\u2193] : Navigate up/down.\n\n[\u2190\u2192 / PgUp / PgDn] : Navigate pages.\n\n[ENTER] : Confirm selection and proceed.\n\n[Q / ESC] : Quit without saving changes.\n\nAfter confirming your selection, the tool will:\n\nCreate/update .summary_files/code_summary.md.\n\nCopy the content of code_summary.md to your clipboard.\n\nSave your selection in .summary_files/previous_selection.json.\n\nIf an OpenAI API key is configured:\n\nIt will ask if you want to generate an AI-powered compressed summary (.summary_files/compressed_code_summary.md).\n\nIf the compressed summary is generated, it will ask if you want to generate/update the root README.md file based on it.\n\n## MCP Server Usage \ud83c\udf10\n\nCodeSum includes an MCP (Model Context Protocol) server that can be used by other AI tools to interact with your codebase programmatically.\n\nTo start the MCP server:\n\n```sh\ncodesum --mcp-server\n```\n\nBy default, the server will run on `localhost:8000`. You can specify a different host and port:\n\n```sh\ncodesum --mcp-server --mcp-host 0.0.0.0 --mcp-port 8001\n```\n\nThe MCP server provides the following endpoints:\n\n- `GET /health` - Health check endpoint\n- `GET /summarize?query=<query>&max_files=<N>` - Generate summary with query parameters\n- `POST /summarize` - Generate summary with JSON body\n\nSee [MCP_USAGE.md](MCP_USAGE.md) for detailed API documentation and usage examples.\n\n## Output \ud83d\udcc2\n\n## Output \ud83d\udcc2\n\nThe tool creates a hidden .summary_files directory in your project root containing:\n\ncode_summary.md:\n\nContains the project structure tree and the full concatenated content of all selected files.\n\nThis content is automatically copied to your clipboard.\n\ncompressed_code_summary.md (Optional - requires API key):\n\nContains the project structure tree and AI-generated summaries for each selected file.\n\nprevious_selection.json:\n\nStores the absolute paths of the files you selected in the last run for this project.\n\n[filename]_metadata.json (Optional - in subdirs matching source):\n\nJSON files (one per AI-summarized file) storing the file's content hash and the generated AI summary for caching purposes.\n\nAdditionally, if you opt-in:\n\nREADME.md (Optional - requires API key):\n\nThe project's main README file may be created or updated with AI-generated content based on the compressed summary.\n\nAnd for configuration:\n\nsettings.env (Located in user config directory, not project dir):\n\nStores your OPENAI_API_KEY and LLM_MODEL.\n\n## Dependencies \ud83d\udcda\n\nCore dependencies (installed automatically via pip):\n\nopenai\n\npathspec\n\npython-dotenv\n\npyperclip\n\nplatformdirs\n\nwindows-curses (on Windows only)\n\nimportlib-resources (on Python < 3.9 only)\n\n## License \ud83d\udcdc\n\nThis project is licensed under the MIT License.\n\n## Acknowledgements \ud83d\ude4c\n\nThanks to the creators of the libraries used in this project and to everyone contributing to the open-source community.\n",
"bugtrack_url": null,
"license": null,
"summary": "Interactive code summarizer using AI and TUI",
"version": "0.2.12",
"project_urls": null,
"split_keywords": [
"code",
" summary",
" ai",
" openai",
" tui",
" curses",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9c114d5c5280d26124833b15fd3aa440ea71969f114181163c13f6c728d0c175",
"md5": "c13cdbfd62e1ab4146bfb6e0b210c10a",
"sha256": "fad1e0e6a19ecdebdebaefc31815cdabda4c17dd8775f4e6c986a9e8cc850604"
},
"downloads": -1,
"filename": "codesum-0.2.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c13cdbfd62e1ab4146bfb6e0b210c10a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37304,
"upload_time": "2025-09-05T21:45:16",
"upload_time_iso_8601": "2025-09-05T21:45:16.106565Z",
"url": "https://files.pythonhosted.org/packages/9c/11/4d5c5280d26124833b15fd3aa440ea71969f114181163c13f6c728d0c175/codesum-0.2.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df1b1ed716e71461ae9629c43b62d940068d5004d1565d2ad9bf7743070ab6d6",
"md5": "a20b7956afb39558f6bdb91f2d86e049",
"sha256": "d70eb7de5ebeae8b95d5e8f2dac9b97ec01f1816edbf58e70526965bf607a10d"
},
"downloads": -1,
"filename": "codesum-0.2.12.tar.gz",
"has_sig": false,
"md5_digest": "a20b7956afb39558f6bdb91f2d86e049",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35883,
"upload_time": "2025-09-05T21:45:17",
"upload_time_iso_8601": "2025-09-05T21:45:17.429984Z",
"url": "https://files.pythonhosted.org/packages/df/1b/1ed716e71461ae9629c43b62d940068d5004d1565d2ad9bf7743070ab6d6/codesum-0.2.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 21:45:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "codesum"
}
JSON