⃤ V R I T R A A I ⃤

Terminal-native AI coding agent for Termux & Linux - pip install, approve diffs, ship

Documentation · Getting started · PyPI · Changelog

🎯 Why VritraAI? Because chatbots paste snippets and IDEs babysit one file.
VritraAI runs an agent loop in your terminal: read the repo, edit multiple
files, run shell, verify, and stop when the task is done - with diffs you approve
first. No server UI. No silent writes.

🧭 Tool Purpose - local coding agent for real project work. Free-tier keys
(Gemini / OpenRouter :free / Groq) are enough to start. Only approve changes
you understand.

📚 Full docs: https://vritraai.vritrasec.com/
(guides, slash commands, providers, approvals, troubleshooting).

📋 Table of contents

• 📸 Preview
• ✨ Features
• 🧠 How it works
• 📦 Installation
• 🚀 Usage
• 🧰 Agent modes
• ⌨️ Slash commands
• 🔌 Providers
• 📁 Where files go
• 🌍 Environment
• 🩺 Setup check
• 📚 Documentation
• ❓ FAQ
• 🔁 Changelog
• ⚠️ Disclaimer
• 📜 License

📸 Preview

Startup banner - type / for commands · plain text runs the coding agent.

vritraai › Scaffold a FastAPI service with /health, pytest, and a short README

· workspace /home/you/demo
· Calling model …
· Create  app/main.py
· Create  tests/test_health.py
· $ python3 -m pytest -q
Done - health route green, README written.

✨ Features

🧠 How it works

flowchart LR
    U["You: plain-language task"] --> L["Agent loop"]
    L --> M["Model + failover"]
    M --> T{"Tools"}
    T -->|read / search| W[("Workspace")]
    T -->|write / shell| A{"Approval"}
    A -->|ok| W
    A -->|deny| M
    W --> M
    M -->|finish_task| D["Done"]

1. You open a folder with vritraai.
2. Plain text becomes a task - the model calls tools in a loop.
3. Writes and shell hit the approval gate (unless trust is auto).
4. The agent verifies work, then calls finish_task with a summary.

Deep dive: Agent loop docs

📦 Installation

Requirements: Python 3.9+ (3.10+ preferred), network for model APIs, at least one provider key. No root.

pip install vritraai

Termux:

pkg install python
pip install vritraai

From source:

git clone https://github.com/MrHacker-X/VritraAI.git
cd VritraAI
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Single-line:

pip install vritraai && vritraai .

The package installs the vritraai console script on your $PATH.

Install guide: vritraai.vritrasec.com/docs/installation/

🚀 Usage

Interactive:

vritraai
vritraai ~/projects/my-app

First session:

/setup          # add Gemini / OpenRouter / Groq / … keys
/model          # pick gemini-flash-latest or openrouter/free
Build a FastAPI /health service with pytest and a short README

1. Choose a permission mode - ask before changes (default), trust this workspace, or strict.
2. Run /setup and add at least one key (free Gemini or OpenRouter is enough).
3. Run /model - good defaults: gemini-flash-latest or openrouter/free.
4. Type a real task. No / prefix = coding agent.

More task ideas:

Add pytest coverage for auth/ and fix whatever fails.
Refactor utils/dates.py to use zoneinfo - keep public API stable.
Scan this repo for common web vulns and open a SECURITY_NOTES.md.

Utilities:

vritraai --help
python -c "import vritraai; print(vritraai.VERSION)"

Quick start: vritraai.vritrasec.com/docs/getting-started/

🧰 Agent modes

Every write and shell command hits the approval gate unless you chose auto.
Failover skips dead model IDs and prefers free-tier routes when paid credits are gone.

Approvals guide: vritraai.vritrasec.com/docs/approvals/

⌨️ Slash commands

Type / for the autocomplete menu.

Aliases: /models → /model, /cheat → /cheatsheet.

Full command reference: vritraai.vritrasec.com/docs/commands/

🔌 Providers

Configure with /setup, pick with /model.

Failover skips dead IDs, avoids burning paid OpenRouter when credits are gone, and keeps other free OpenRouter models after a single 429.

Providers guide: vritraai.vritrasec.com/docs/providers/

📁 Where files go

~/.config-vritrasecz/vritraai/     ← user config (outside any repo)
├── config.json                   ← API keys, model, trust
└── session.log

your-project/                     ← the folder you opened with vritraai
└── .vritraai/
    └── agent_memory.json         ← workspace-scoped agent memory

• Keys never live in the git tree - config is under ~/.config-vritrasecz/.
• .vritraai/, .env, and local secrets are gitignored.
• Config reference: vritraai.vritrasec.com/docs/configuration/

🌍 Environment

🩺 Setup check

vritraai .
# then inside the REPL:
/setup
/model
/help

Stuck? Troubleshooting

📚 Documentation

Serve the local docs tree:

cd vritraai-docs && python3 -m http.server 8080
# open http://127.0.0.1:8080/

❓ FAQ

Do I need a paid API key?
No. A free Gemini key or OpenRouter :free models are enough; Groq free tier works well as failover.

Where are my keys stored?
~/.config-vritrasecz/vritraai/config.json - outside any repository, never committed.

What happened to the old 0.30.x shell?
Previous product line. From 1.0.0-cli VritraAI is a coding agent - see CHANGELOG.md and About.

Can the agent touch files outside my project?
It works inside the workspace you open; every write or shell command is gated by your approval mode.

Where is the full manual?
https://vritraai.vritrasec.com/

🔁 Changelog

1.0.0-cli - full rewrite (the upgrade from ≤0.30.x)

Full history: CHANGELOG.md.

⚠️ Disclaimer

VritraAI can read, write, and run shell commands inside the workspace you open.
You are responsible for the keys you configure, the diffs you approve, and the
commands you allow. Do not point it at folders or credentials you are not
allowed to modify. Treat it as a powerful local tool - review every change.

Security notes: vritraai.vritrasec.com/docs/security/ · Contact: [email protected]

📜 License

Released under the MIT License - see LICENSE.

MIT © Alex Butler / Vritra Security Organization

🔗 Links