stacksense-cli 0.1.3

AI-powered code intelligence for developers

🧠 StackSense

AI-Powered Code Intelligence for Developers

StackSense is a powerful CLI tool that brings AI-driven code understanding to your terminal. Powered by multiple AI providers for flexibility and performance.

Created by: Pilgrimstack

---

✨ Features

🗣️ Interactive AI Chat

• Natural conversations about your code
• Context-aware AI with full repository understanding
• Code generation with permission workflow
• Multi-provider support (OpenRouter, OpenAI, Grok, TogetherAI)

📊 Diagram-First Workflow

• AI creates architecture diagrams before coding
• Iterative refinement with user approval
• Tech stack capture for future sessions

🔧 Agentic Code Modification

• AI proposes changes, you approve
• File/folder creation with explicit permission
• Command execution with user confirmation
• Quality-focused task chunking

🧠 Persistent Memory

• AI remembers what it learns about your codebase
• Cross-session knowledge retention
• Automatic learning from approved changes
• Storage at ~/.stacksense/{workspace}/{repo}/

📊 Dependency Diagrams

• Automatic dependency graph generation
• Multi-language support (Python, JavaScript, TypeScript, Go, Rust)
• Export to JSON, DOT, and Mermaid formats
• Programmatic diagram modification (add/remove nodes and edges)

🔍 Intelligent Repository Scanning

• Smart file discovery with gitignore support
• Language detection and framework identification
• Incremental scanning with caching

🌐 Web Search Integration

• Deep search: AI fetches and reads actual page content
• Prioritizes StackOverflow, GitHub, Reddit, Medium, Dev.to
• Rate limited to prevent abuse

🔄 Dynamic Model Switching

• Switch between 100+ models on-the-fly
• One-shot model usage: model:qwen2.5 your question
• Permanent switching: /model llama-3.3-70b
• Works best with OpenRouter for maximum flexibility

---

🚀 Installation

Basic Install (Python 3.9+)

pipx install stacksense-cli
# Or with pip:
pip install stacksense-cli

✅ All 40+ AI tools work with regex-based code parsing

Full Install (Python 3.9-3.12)

pipx install "stacksense-cli[full]"
# Or with pip:
pip install "stacksense-cli[full]"

✅ Enhanced syntax parsing with tree-sitter for more accurate diagrams

Note: Tree-sitter support requires Python <3.13. On Python 3.13+, StackSense automatically falls back to regex parsing.

Development Install

git clone https://github.com/AmariahAK/Stacksense.git
cd stacksense
pip install -e ".[dev]"

Prerequisites

• Python 3.9+ (3.9-3.12 for full tree-sitter support)
• API Key from your chosen provider

API Key Setup

StackSense v1.0 supports OpenRouter only. More providers coming soon!

⚠️ Note on AI Model Reliability
AI models (both free and paid) may occasionally hallucinate, lose context, or fail to call tools correctly—especially older models. We've optimized StackSense to minimize these issues and provide a seamless experience, but occasional quirks may occur. For best results, use newer models like GPT-5, Claude 4.5, Gemini 3, or Grok 4.

# OpenRouter (available in v1.0 - access to 100+ models)
OPENROUTER_API_KEY="sk-or-v1-your-key-here"

# Coming in v2.0:
# OLLAMA - Local models (no API key needed)

# Coming in v3.0:
# OPENAI_API_KEY="sk-your-key-here"
# GROK_API_KEY="xai-your-key-here"
# TOGETHER_API_KEY="your-key-here"

---

📖 Quick Start

Initial Setup

# Configure AI provider
stacksense --setup-ai

# Run diagnostics (check configuration)
stacksense doctor

Start AI Chat

# Chat with repository context
stacksense chat

# Chat with a specific workspace
stacksense chat --workspace ~/projects/myapp

Credits & Account Management

# View your current credit balance
stacksense credits

# Buy more credits (opens pricing page)
stacksense upgrade

# Redeem a license key after purchase
stacksense redeem YOUR-LICENSE-KEY

# Login on a new device to restore credits
stacksense login [e-mail] YOUR-ORDER-KEY

# Check account status
stacksense status

---

🤖 Supported AI Providers

Provider	Description	Status	Version
OpenRouter	Multi-provider gateway	✅ Available	v1.0
Ollama	Local models	🔜 Coming	v2.0
OpenAI	GPT-4, GPT-4o	🔜 Coming	v3.0
Grok (xAI)	Grok-2, real-time	🔜 Coming	v3.0
TogetherAI	Llama, Qwen, Mistral	🔜 Coming	v3.0

Recommended: OpenRouter

OpenRouter is the only provider in v1.0 because it provides access to 100+ models from multiple providers (OpenAI, Anthropic, Google, Meta, Mistral, etc.) through a single API key. This gives you maximum flexibility while we work on adding more providers.

Get your free API key: openrouter.ai/keys

Tool Calling

All providers share 40 tools through our unified agent architecture with smart slicing support:

Free Tools (0 credits)

Tool	Description
ask_user	Request permission for actions
stop_command	Stop a running terminal command
git_status	Show changed/staged/untracked files
slice_output	AI-controlled re-slicing of content

Basic Tools (1 credit)

Tool	Description
get_diagram	View codebase structure
read_file	Read file contents (with smart slicing)
search_code	Search for keywords
recall_memory	Get previous learnings
list_tasks	View current tasks
update_diagram	Modify diagram incrementally
recall_search_learnings	Check saved search insights
list_groups	View file groups
git_diff	Show git changes
find_file	Find files by pattern
summarize_file	One-line file summary
get_dependencies	List project dependencies
hot_reload_status	Check dev server status

Medium Tools (2-3 credits)

Tool	Description	Credits
save_learning	Save insights (replaces existing)	2
save_search_learning	Save web search insight	2
create_task	Create a task	2
update_task	Mark task done/blocked	2
clear_tasks	Clear all tasks	2
group_files	Group related files together	2
dependency_tree	Show why package is installed	2
explain_error	Parse error messages	2
analyze_stack_trace	Extract stack trace info	2
estimate_complexity	File complexity score	2
code_smell_scan	Find code issues	2
project_health	Overall project health check	2
suggest_related_files	Find related files	2
create_snippet	Save code snippets	2
read_url	Fetch HTTPS URLs	2
web_search	Deep web search	3
write_file	Create/modify files	3
run_command	Execute terminal commands	3
run_tests	Execute test suite	3

Premium Tools (4-5 credits)

Tool	Description	Credits
diagram_generate	Generate architecture diagram	4
agent	Spawn sub-agent	5
repo_scan	Full repository scan	5

---

🔧 Tab Completion

Press Tab to trigger the dropdown menu. Type a prefix, then press Tab to see options:

Prefix	Action	Example
model: + TAB	Select model for one query	model:qwen
/model + TAB	Select model permanently	/model llama
@ + TAB	Attach file to context (5 max)	@src/main.py

Note: Dropdowns show 5 items at a time. Use ↑↓ arrows to navigate, Tab/Enter to select.

---

🔍 Web Search

StackSense has two search modes:

Regular Search (search: command)

search:python asyncio best practices

Returns URLs and short snippets.

Deep Search (AI fetches full pages)

search:deep python asyncio best practices

AI visits top 5 results, reads full content, and summarizes.

---

📊 Task Management

StackSense tracks your progress with todo.json:

{
  "project": "my-app",
  "tasks": [
    {
      "id": 1,
      "title": "Implement auth",
      "status": "done",
      "completed_at": "2024-12-09T10:00:00Z"
    },
    {
      "id": 2,
      "title": "Add user model",
      "status": "in_progress",
      "started_at": "2024-12-09T11:00:00Z"
    }
  ],
  "total": 10,
  "completed": 1
}

---

🧠 Memory System

StackSense remembers what it learns:

{
  "learnings": {
    "authentication": {
      "summary": "JWT with PyJWT, 15min expiry",
      "files": ["auth/jwt.py", "auth/middleware.py"]
    }
  },
  "patterns": {
    "error_handling": "Return JSON with status and message"
  }
}

---

🔐 License System

StackSense uses a secure license system:

# View status
stacksense status

# Activate key
stacksense set-key YOUR-KEY

---

📚 Documentation

Full documentation: stacksense-docs.vercel.app

Additional Docs

• Known Limitations - Free model behavior and workarounds
• AI Models - Provider setup and model recommendations
• Chat Interface - Commands and features
• Diagram System - Architecture visualization

---

💬 Community

Join our Discord: discord.gg/stacksense

---

📜 License

MIT License. See LICENSE.md for full details.

Copyright (c) 2024 Pilgrimstack.