brainet 0.2.3

AI-powered development context tracker - never lose your train of thought

🧠 Brainet

Never lose your train of thought again.

Brainet is an AI-powered development context tracker that automatically captures what you're working on, why you're working on it, and what's next. Think of it as a second brain for your coding sessions.

---

🚀 What's New in v0.2.0

Major Architecture Overhaul - 5-Source Intelligence System:

• 🔍 SOURCE 1 - Git Diffs: Smart chunking with AST-based function extraction
• 📄 SOURCE 2 - Full Files: Complete code context for accurate answers
• 🌲 SOURCE 3 - AST Analysis: Deep code structure understanding (classes, methods, imports)
• 🎯 SOURCE 4 - Semantic Search: Proactive code discovery related to your queries
• 📦 SOURCE 5 - Project Metadata: Dependencies, file types, and project structure

Critical Bugs Fixed:

• ✅ Ask command now provides specific, detailed answers with line numbers
• ✅ Proper diff counting (additions/deletions) in all scenarios

New Features:

• 🎨 Capsule indexing (#01, #02, #03 format)
• 👁️ brainet preview <index> - View any historical capsule
• 💬 Dramatically improved AI responses - specific method listings, accurate context

---

🤔 The Problem

You're deep in the zone, building a feature. Then...

• 📧 An urgent email arrives
• 🔥 A production bug needs fixing
• ☕ You take a break
• 📅 It's Friday, you'll continue Monday

Monday morning: "Wait... what was I doing? Why did I change this file? What was the plan?"

You spend 30 minutes scrolling through git commits, reading code, trying to remember. Your flow state? Gone.

✨ The Solution

Brainet captures your coding sessions automatically and uses AI to create human-readable summaries:

$ brainet capture

📸 Context Captured
────────────────────────────────────────────────────────────────
Added a Character class with methods for combat (attack, 
take_damage, heal), progression (gain_experience, level_up), 
and status checking (is_alive). Also added Inventory class 
with item management.

📊 Stats:
   • 1 files modified
   • 67 lines added
   • 3 TODOs found

✓ Capsule saved: 2025-11-02 15:45:53
────────────────────────────────────────────────────────────────

Now when you come back, just run brainet history and instantly remember everything.

---

🚀 Quick Start

Installation

# 1. Install brainet
pip install brainet --user

# 2. Add to PATH permanently
echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Setup

# 1. Check it works
brainet --version

# 2. Get free API key from https://console.groq.com/keys

# 3. Set it permanently
echo 'export GROQ_API_KEY="gsk_your_key_here"' >> ~/.zshrc
source ~/.zshrc

# 4. Start using brainet in any git project!
cd your-project

brainet start
# ... make some changes ...
brainet capture --tag feature -m "Added user authentication"

That's it! Brainet is now tracking your development context.

---

💡 Key Features

🤖 AI-Powered Summaries

Brainet uses Claude Sonnet 3.5 (via Groq) to understand your changes and generate intelligent summaries. It knows the difference between:

• Major features vs minor refactors
• Bug fixes vs new functionality
• Breaking changes vs safe updates

🔍 Natural Language Querying (Powered by 5 Sources)

Ask questions about your work in plain English - now with comprehensive context:

$ brainet ask "what methods does the Character class have?"

You have a Character class with these methods: __init__ 
(lines 4-10), take_damage (lines 12-15), heal (lines 17-20), 
is_alive (lines 22-23), attack (lines 25-27), gain_experience 
(lines 29-32), and level_up (lines 34-39). The TODOs include 
adding a magic system with spells, implementing quest tracking, 
and adding save/load game functionality.

v0.2.0 Intelligence: Brainet now searches through full file contents, AST structure, and semantically related code to give you accurate, detailed answers with line numbers.

🏢 Multi-Project Support

Working on multiple projects? Brainet handles it seamlessly:

$ brainet workspaces

📚 Active Brainet Sessions (3):
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Project      ┃ Location               ┃ Capsules ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ api-backend  │ ~/projects/api         │       12 │
│ frontend-app │ ~/projects/frontend    │        8 │
│ mobile-app   │ ~/projects/mobile      │        5 │
└──────────────┴────────────────────────┴──────────┘

📍 Note: The workspaces command scans these directories for brainet projects:

• ~/Desktop - For desktop projects
• ~/Documents - For document-based work
• ~/Projects - For dedicated project folders

Keep your projects in these locations for automatic discovery!

🔎 Cross-Project Search

Find where you implemented that feature across all your projects:

$ brainet search "authentication" --all-projects

🔍 Found in 3 projects:
  • api-backend: JWT authentication with refresh tokens
  • frontend-app: Google OAuth integration
  • mobile-app: Biometric authentication added

📊 Development Analytics

Understand your coding patterns:

$ brainet stats

📊 Development Insights
────────────────────────────────────────
  Sessions: 47
  Files modified: 234
  Most active file: auth.py (23 changes)
  Top tags: feature, bugfix, refactor
  
  Recent activity:
  • 15 sessions this week
  • Peak productivity: Tuesday afternoons
────────────────────────────────────────

---

📚 Commands

Command	Description
brainet start	Initialize tracking in current project
brainet capture	Save current session with AI summary
brainet history	View all captured sessions with #01, #02 indexing
brainet preview	Preview what will be captured next
brainet preview <N>	View historical capsule #N
brainet ask "question"	Query your work with AI (v0.2.0: 5-source intelligence)
brainet search "keyword"	Search across sessions
brainet workspaces	List all tracked projects
brainet stats	View development analytics
brainet export	Export sessions to Markdown
brainet diff <file>	View colorized file changes
brainet switch	Quick navigation between projects

Run brainet --help for full command list.

---

🎯 Real-World Use Cases

1. Context Switching

Switch between tasks without losing context:

# Working on Feature A
brainet capture --tag feature-a

# Emergency bug fix needed
brainet pause
cd ~/other-project
brainet start
# Fix bug...
brainet capture --tag hotfix

# Back to Feature A
cd ~/original-project
brainet resume  # Instantly recall where you left off

2. Code Reviews

Generate PR descriptions automatically:

brainet export --since yesterday

# Copy the AI-generated summary into your PR

3. Weekly Standups

"What did I work on this week?"

brainet history --since "1 week ago"

# See all your accomplishments summarized

4. Knowledge Transfer

Onboarding a teammate:

brainet export --tag authentication > auth_work.md

# Share the complete history of authentication feature

---

🛠️ How It Works

1. File Watching - Tracks changes in your git repository
2. Git Integration - Captures commits, diffs, and file changes
3. TODO Extraction - Finds TODO comments automatically
4. AI Analysis - Claude Sonnet 3.5 generates intelligent summaries
5. Local Storage - Everything saved locally in .brainet/ folder

Privacy First: All your data stays on your machine. AI summaries are generated via API but your code never leaves your control.

---

🔧 Configuration

API Keys

Brainet supports two AI providers:

Groq (Recommended) - Free, fast, 500+ tokens/sec

export GROQ_API_KEY="your_key_here"

Anthropic Claude - More powerful, requires paid account

export ANTHROPIC_API_KEY="your_key_here"

Advanced Options

# Capture with custom tags
brainet capture --tag feature --tag auth -m "Added JWT support"

# Export filtered sessions
brainet export --tag bugfix --since "2024-10-01"

# Search in current project only
brainet search "payment integration"

# Clean up old sessions
brainet cleanup --days 90

---

🎓 Best Practices

1. Capture Often - At least once per coding session
2. Use Tags - Organize with --tag feature, --tag bugfix, etc.
3. Add Messages - Use -m for important context
4. Regular Cleanup - Run brainet cleanup monthly
5. Export Important Work - Save milestones to Markdown
6. Organize Projects - Keep projects in ~/Desktop, ~/Documents, or ~/Projects for the workspaces command to find them automatically

---

🤝 Contributing

Brainet is open source! Contributions welcome:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Built with Anthropic Claude
• Powered by Groq for fast AI inference
• Uses Rich for beautiful terminal output
• Created for developers, by developers

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Stop losing context. Start using Brainet.

Made with ❤️ for developers who value flow state