veni-ai

---

✨ Features

🎯 Core

🖥️ Shell Execution	Run commands with approval gates, output limits, and risk-tiered safety
📝 File Editing	Write, patch, and diff — preview before applying
🔎 Repo Search	Read and index project files for context-aware answers
🧭 Session Control	Save, load, export, resume — never lose a thread

🧩 Intelligence Layer

🧠 Skills System	21 skills auto-activate by context — debugging, data analysis, security, more
🎭 Personas	Switch AI behavior: Expert, Teacher, Critic, Coach, Creative...
💬 Response Modes	Detailed, Concise, Socratic, Step-by-Step, Academic...
🔍 Cross-Reference	Symbol search, import graph, impact analysis before changes

🔌 Extensibility

🧩 Plugin System	Drop a .py file in plugins/ — instant new commands
🔌 MCP Support	Model Context Protocol — connect any MCP tool server
📦 12 Providers	Ollama (local), OpenAI, Gemini, Anthropic, Groq, free, and more
📱 Telegram Gateway	Chat with Veni from your phone

🛡️ Safety

🛡️ Approval Gates	Risk-tiered — blocks rm -rf, fork bombs, dangerous ops
📁 Workspace Isolation	All file ops constrained to your project
🔒 PII Redaction	API keys, tokens, emails auto-masked in exports

⚠️ Security Notice: The approval gate is best-effort. For strong isolation, run in a container or VM.

---

🚀 Quick Start

# Install
pip install veni-ai

# Initialize (interactive wizard)
veni init

# Launch
veni chat --provider ollama --model llama3.2

Try it now — no API key needed

# Free tier (no setup)
veni chat --provider duckduckgo
veni chat --provider free

# Or use Ollama (local)
ollama pull llama3.2
veni chat --provider ollama --model llama3.2

One-shot / pipe mode

veni pipe "explain this error: TypeError: ..."
echo "review this code" | veni pipe
veni pipe "fix bugs in main.py" --provider openai

---

🧠 Provider Support

Provider	Privacy	Tool Use	Cost	Quick Start
🦙 Ollama	🔒 100% Local	✅	🆓 Free	ollama pull llama3.2
🧠 OpenAI	☁️ Cloud	⚡ Native	💸 Paid	set OPENAI_API_KEY
💎 Gemini	☁️ Cloud	⚡ Native	💸 Tiered	set GEMINI_API_KEY
🤖 Anthropic	☁️ Cloud	⚡ Native	💸 Paid	set ANTHROPIC_API_KEY
⚡ Groq	☁️ Cloud	✅	🆓 Free	set GROQ_API_KEY
🆓 Free	☁️ Cloud	⚠️ Limited	🆓 Free	no key needed
🌐 DuckDuckGo	☁️ Cloud	❌	🆓 Free	no key needed
🔷 DeepSeek	☁️ Cloud	✅	💸 Paid	set DEEPSEEK_API_KEY
🏔️ Mistral	☁️ Cloud	✅	💸 Paid	set MISTRAL_API_KEY
🔀 OpenRouter	☁️ Cloud	✅	💸 Paid	set OPENROUTER_API_KEY
🐪 Qwen	☁️ Cloud	✅	💸 Paid	set QWEN_API_KEY
🔮 Perplexity	☁️ Cloud	❌	💸 Paid	set PERPLEXITY_API_KEY

---

🎮 Command Reference

Command	Action
/new	Start a new conversation
/save [name]	Save current session
/load <name>	Load a saved session
/history	List saved sessions
/export <md|txt|json>	Export session
/quit / /exit / /q	Exit Veni

Command	Action
/model	Switch provider and model
/system	Show system info
/temperature [value]	Set generation temperature
/top_p [value]	Set nucleus sampling
/max_tokens [value]	Set response length limit
/template	Set prompt template
/status	Show session stats
/plan [on|off|status]	Toggle autonomous planning mode

Command	Action
/persona [name|list|current|auto]	Switch AI persona (12 built-in)
/mode [name|list|current]	Switch response style (11 modes)

Command	Action
/skill list	List all skills with active status
/skill search <query>	Find skills by keyword
/skill enable <name>	Enable a skill
/skill disable <name>	Disable a skill
/skill status	Show active skills
/skill auto <query>	Auto-detect skills for a query

Command	Action
/pwd	Show working directory
/ls	List files
/cd <path>	Change directory
/read <file>	Read file into context
/edit <file>	Ask AI to edit a file
/tree	Show project structure
/xref <symbol>	Find symbol cross-references

Command	Action
/diff	Show syntax-highlighted git diff
/commit	AI generates commit message
/commit --review	AI reviews changes before commit
/log	Show recent commit history

Command	Action
/approve	Toggle approval gate
/debug	Analyze error output
/search <query>	Web search
/scrape <url>	Scrape web page content
/pdf <url>	Extract text from PDF URL

Command	Action
/copy	Copy last response to clipboard
/pin / /unpin / /pins	Pin/unpin responses
/retry	Re-generate last response
/summary	Summarize conversation
/alias	Create command alias
/clear	Clear screen
/theme	Switch theme
/banner	Toggle compact header mode
/voice	Toggle voice mode
/image <path>	Attach image
/stats	Show usage statistics
/help	Full help

---

🔌 MCP Integration

Veni supports the Model Context Protocol for tool extensibility.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

MCP tools auto-register on startup alongside native tools.

---

🧩 Plugin System

Drop a Python file into plugins/:

# plugins/my_plugin.py
PLUGIN_COMMANDS = {
    "/greet": lambda args: f"Hello, {args[0] if args else 'World'}!",
}
PLUGIN_HELP = {
    "/greet": "Say hello to someone.",
}

---

📊 vs Alternatives

Feature	Veni AI	Claude Code	Aider	Open Interpreter
Shell Execution	✅	✅	✅	✅
Multi-File Editing	✅	✅	✅	✅
Local Models	✅	❌	✅	✅
Free Tier	✅	❌	❌	✅
MCP Support	✅	✅	❌	❌
Plugin System	✅	✅	❌	❌
Skills System	✅	❌	❌	❌
Personas & Modes	✅	❌	❌	❌
Voice Mode	Optional	❌	❌	❌
Pipe/CI Mode	✅	❌	❌	❌
Approval Gates	✅	✅	❌	❌
Web Dashboard	Optional	❌	❌	❌
12 AI Providers	✅	❌	❌	❌
Semantic Memory	Optional	❌	❌	❌

---

🏗️ Architecture

veni/
├── core.py              # Bot orchestration
├── session.py           # Main run loop
├── chat_engine.py       # Streaming, retry, tool calls
├── cli.py               # Typer CLI entry point
├── config.py            # YAML config management
├── approval.py          # Safety approval gate
├── providers/           # 12 AI provider implementations
├── commands/            # 45+ slash commands
├── tools/               # 12 AI-accessible tools
├── skills/builtins/     # 21 SKILL.md definitions
├── personas/builtins/   # 12 persona YAML files
├── modes/builtins/      # 11 mode YAML files
├── memory.py            # Vector semantic memory
├── indexer.py           # Codebase indexer (10+ langs)
├── mcp.py               # MCP client adapter
├── server.py            # FastAPI dashboard
├── scheduler.py         # Background tasks
├── gateways/            # Telegram bridge
├── plugins/             # Drop-in plugin directory
└── tests/               # 286+ tests

---

🛠 Development

git clone https://github.com/neoastra303/Veni-AI.git && cd Veni-AI
pip install -e ".[dev]"
pre-commit install

# Full quality check
make check

# Or individual steps
make format       # black
make lint         # ruff
make typecheck    # mypy
make test         # pytest with coverage
make security     # bandit scan

286+ tests · 70%+ coverage · CI/CD · CodeQL · Dependabot

---

🤝 Contributing

🐛 Report Bug	💡 Request Feature
🔧 Open PR	⭐ Star the Repo
📖 Contributing Guide	🏗️ Architecture

---

🤝 Contributors

• neoastra303 - Lead Developer