🧠 project-brain
Local-first developer intelligence CLI for semantic repository analysis, Git-aware code understanding, and AI-friendly engineering workflows.
🚀 What is project-brain?
project-brain is a CLI-first developer intelligence tool built for analyzing codebases, tracking Git changes at function level, generating structured exports for AI systems, and explaining code changes using optional LLM integrations.
Unlike traditional Git tooling that operates on raw line diffs, project-brain uses AST-based parsing to understand code structure and produce developer-friendly insights.
The project is designed around a local-first, privacy-friendly, and AI-optional workflow.
🎯 Why project-brain Exists
Modern development workflows suffer from several problems:
Git diffs are noisy
Traditional diffs show line changes, not semantic meaning.
A small refactor can generate large diffs while hiding the actual behavioral impact.
Codebases become difficult to understand
Large repositories contain:
- deeply nested modules
- duplicated logic
- unclear ownership
- hidden dependencies
Understanding them manually is slow.
AI tools require structured context
Most AI systems perform poorly when fed raw repositories.
project-brain creates:
- structured exports
- focused change sets
- function-level intelligence
- AI-friendly context
✨ Features
Implemented
- 🔍 Recursive repository scanning
- 🧠 AST-based Python analysis
- 🧩 Function extraction
- 🏛️ Class extraction
- 🔄 Git diff parsing
- 📌 Function-level change tracking
- 📦 AI-friendly code export system
- 🤖 Optional LLM explanations
- 💾 Explanation caching
- 🌐 HTML diff reports
- ⚠️ Config validation
- 🩺 Environment diagnostics
- 🪵 Persistent logging
- 🚫 Binary file skipping
- 🛡️ Invalid Python safety handling
- ⚡ Deep directory traversal
⚙️ Installation
Requirements
-
Python >= 3.10
-
Git installed
-
Optional:
- Ollama
- OpenAI API access
- Gemini API access
- HuggingFace API access
Install from PyPI
pip install project-brain-cli
Verify Installation
brain --version
Upgrade
pip install --upgrade project-brain-cli
CLI Aliases
Both commands work:
brain
project-brain
⚡ Quick Start (30 Seconds), For More INFO Click
1. Initialize project-brain
brain project init
Demo:
Creates:
.brain/
brain.yaml
2. Analyze Repository
brain project analyze .
Demo:
Performs:
- recursive scan
- AST parsing
- metadata generation
Stores results inside:
.brain/data.json
3. Inspect Git Changes
brain diff show
Demo:
Default behavior:
HEAD~1 → HEAD
Shows:
- modified files
- added files
- deleted files
- function-level changes
4. Export AI-Friendly Context
brain export full-code
Demo:
Creates:
.brain/exports/full_code.txt
5. Diagnostics
Validate project readiness:
brain project doctor
Demo:
Checks:
- git availability
- project initialization
- analysis freshness
- export availability
- provider configuration
- API key presence
6. Access Community Resources
brain community
Demo:
Open feedback/discussions directly:
brain --feedback
🧪 LLM Commands
brain testllm test
Test provider connectivity.
Syntax
brain testllm test
What It Does
- loads provider config
- sends test prompt
- validates response
- optionally fetches model list
Disabled Mode
If:
provider: none
Output:
LLM disabled
⚙️ Configuration
Configuration file:
brain.yaml
Example Configuration
version: "1.2.0"
llm:
provider: none
model: ""
timeout_sec: 60
analysis:
depth: fast
include_tests: false
ignore:
- .brain/
- .git/
- node_modules/
- venv/
- .venv/
- __pycache__/
- env/
- .env/
- project_brain_cli.egg-info/
- tests/
- test/
diff:
mode: function
export:
full_code:
include_tests: false
max_file_size_kb: 200
manual_add:
allow_duplicates: true
changes:
mode: function
include_context: true
output_path: .brain/exports/code_changes.txt
ignore:
- .brain/
- .git/
- node_modules/
- venv/
- .venv/
- __pycache__/
- env/
- .env/
- project_brain_cli.egg-info/
- tests/
- test/
explain:
level: detailed
include_risks: true
output:
format: text
🔑 API Key Setup
Secrets should NEVER be stored inside brain.yaml.
Windows CMD
setx OPENAI_API_KEY "your_key"
setx GEMINI_API_KEY "your_key"
setx HUGGINGFACE_API_KEY "your_key"
PowerShell
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY","your_key","User")
Linux/macOS
export OPENAI_API_KEY="your_key"
📴 Offline Mode
project-brain fully supports offline workflows.
Use:
llm:
provider: none
Behavior:
- no API calls
- no cloud dependency
- local-only analysis
- fallback explanations enabled
📄 Example Outputs
Analysis
🔍 Analyzing: .
📋 File Paths:
src/api.py
src/utils.py
✅ Analysis complete
Diff Review
Function: create_user
Change:
Added validation layer
Impact:
Improves input integrity
Risk:
medium
🏗️ Architecture
CLI Layer
│
├── Analyzer Engine
├── Diff Engine
├── Explain Engine
├── Export Engine
├── Diagnostics Layer
├── Config Validation
├── Logging System
└── LLM Provider Layer
🔄 Supported Providers
| Provider | Supported |
|---|---|
| OpenAI | ✅ |
| Ollama | ✅ |
| Gemini | ✅ |
| HuggingFace | ✅ |
| Offline Mode | ✅ |
🪵 Logging System
Logs stored inside:
.brain/logs.txt
Tracks:
- warnings
- provider failures
- parsing errors
- export failures
- cache issues
Logging failures never crash the CLI.
🛠️ Troubleshooting
❌ Not a git repository
Initialize git:
git init
❌ Invalid git reference
Check refs:
git log --oneline
❌ Empty export
Possible causes:
- ignored paths
- file size limits
- tests excluded
❌ Provider failures
Check:
- API keys
- internet connectivity
- provider model name
❌ Missing API key
Verify environment variable:
echo %OPENAI_API_KEY%
🧪 Testing & QA
Current QA status:
- 18 automated tests passing
- export validation
- function diff validation
- config validation
- edge-case handling
- provider fallback testing
🔮 Roadmap
Near-Term
- semantic diff intelligence
- integration tests
- incremental analysis
- performance improvements
- rename detection
Mid-Term
- multi-language parsing
- plugin architecture
- dependency graphing
- richer semantic indexing
🔐 Security & Privacy
project-brain is designed with a local-first philosophy.
Key principles:
- no automatic code uploads
- offline workflows supported
- API keys via environment variables only
- repository data stored locally
LLM usage is fully optional.
🤝 Contributing
Contributions are welcome.
Recommended workflow:
git checkout -b feature/my-feature
Guidelines:
- keep PRs focused
- preserve CLI consistency
- add tests for new logic
- avoid unnecessary dependencies
📜 License
MIT License
🧠 Final Positioning
project-brain is a local-first developer intelligence CLI that transforms repositories and Git diffs into structured, explainable engineering context.
Metadata
Release files for project-brain-cli 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| project_brain_cli-1.2.0.tar.gz | 48.9 kB | Without provenance | Details for project_brain_cli-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| project_brain_cli-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for project_brain_cli-1.2.0-py3-none-any.whl |
Total release size: 107.1 kB
Release files / project_brain_cli-1.2.0.tar.gz
| Download URL | project_brain_cli-1.2.0.tar.gz |
|---|---|
| Size | 48.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
141023722059a8d923cdc23149f7cf0cf56661b02b17839e1e215d3e29c68d82
|
|
BLAKE2b-256 checksum How to use checksums |
b04a1aa0d1ef3bc382dab91a9ab28065428a4c38b6ce991808f8ceee8b738792
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Release files / project_brain_cli-1.2.0-py3-none-any.whl
| Download URL | project_brain_cli-1.2.0-py3-none-any.whl |
|---|---|
| Size | 58.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d55842867bbaac7af433eb87490b043bc1ea1136d7af90716191c49954b69da
|
|
BLAKE2b-256 checksum How to use checksums |
fefbd4e0508bf5ff49e7fdaa37873a13c8a89a5a4feb09f9a77b6afd4e9d4b10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.0
|
Security for project-brain-cli 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.