codrninja 1.0.0

AI-first coding assistant with TypeScript TUI

🥷 codrninja

AI-first coding assistant for automation. A lightweight, programmatic alternative to interactive coding tools like OpenCode or Claude Code.

🔌 Multi-Provider Support

Works with any AI provider:

Provider	Setup	Models
Ollama (default)	Local server	codellama, llama2, mistral
OpenAI	API key	gpt-4, gpt-4-turbo, gpt-3.5
Anthropic	API key	claude-3-opus, claude-3-sonnet
OpenRouter	API key	Access to all major models

Provider Configuration

# Ollama (default)
export OLLAMA_URL=http://localhost:11434
export OLLAMA_MODEL=codellama

# OpenAI
export OPENAI_API_KEY=sk-...
export CODRNINJA_PROVIDER=openai
export CODRNINJA_MODEL=gpt-4

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export CODRNINJA_PROVIDER=anthropic
export CODRNINJA_MODEL=claude-3-sonnet-20240229

# OpenRouter
export OPENROUTER_API_KEY=sk-or-...
export CODRNINJA_PROVIDER=openrouter
export CODRNINJA_MODEL=openai/gpt-4

🚀 Quick Install

🚀 Quick Install

macOS / Linux

pip3 install codrninja

If codrninja-tui is not found after installation, your pip user directory isn't in PATH. Fix it:

# For macOS (Python 3.x)
echo 'export PATH="$HOME/Library/Python/3.14/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For Linux
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Or use the automatic installer:

curl -fsSL https://raw.githubusercontent.com/20ZollCoder/codrninja/main/install.sh | bash

From source

git clone https://github.com/20ZollCoder/codrninja.git
cd codrninja
pip3 install -e .

⚡ Quick Start

# Set your provider (Ollama is default)
export OLLAMA_URL=http://localhost:11434

# Or use OpenAI
# export OPENAI_API_KEY=sk-...
# export CODRNINJA_PROVIDER=openai

# Start interactive TUI
codrninja-tui my-project

# Or use agent mode
codrninja agent my-project "Create a Button component"

🎯 Features

For Humans (TUI Mode)

• 🎨 Beautiful terminal UI with ASCII art welcome
• 💻 Syntax highlighting for code blocks
• 📊 Tool usage tables
• ⌨️ Slash commands (/help, /files, /read, /exec)
• ⚡ Progress indicators

For AI Systems (Automation Mode)

• 🤖 Agent loop with tool execution
• 🛠️ Read, write, edit files automatically
• 🔧 Execute shell commands
• 📤 JSON output for scripting
• 🧠 Session-based conversations

📖 Usage

Interactive TUI

# Start TUI
codrninja-tui my-project

# Inside TUI:
You: Create a Button component in React
🤖 AI: I'll create that for you...
✅ Tool: write_file → src/components/Button.jsx
✅ Tool: execute_command → npm test (passed)

You: /read src/components/Button.jsx
📄 (shows file with syntax highlighting)

You: /exec npm run build
⚡ (runs build command)

You: /help
📖 (shows all commands)

Agent Mode (Scripting)

# Set automation mode
export AI_CODE_MODE=automation

# Run agent with auto-approval
codrninja agent my-project "Create a login form"

# Continue conversation
codrninja agent my-project "Add validation to the form"

Commands

Command	Description
codrninja-tui <session>	Start interactive TUI
codrninja agent <session> "msg"	Run agent with tools
codrninja send <session> "msg"	Send message
codrninja create-session <name>	Create session
codrninja show-session <name>	Show history

TUI Slash Commands

Command	Description
/help	Show help
/files	List files
/read <file>	Read file
/write <file>	Write file (interactive)
/exec <cmd>	Execute command
/model	Show AI model config
/session	Show session info
/clear	Clear screen
/exit	Quit

🔧 Configuration

# Environment variables
export OLLAMA_URL=http://localhost:11434    # Ollama endpoint
export OLLAMA_MODEL=codellama                 # Default model
export AI_CODE_MODE=automation                # JSON output mode

🆚 Comparison with OpenCode

Feature	OpenCode	codrninja
Size	~146MB Go binary	~8KB Python
TTY Required	❌ Yes	✅ No
JSON Output	❌ No	✅ Yes
Agent Loop	✅ Yes	✅ Yes
Tool Execution	✅ Yes	✅ Yes
Session API	Hidden	Simple CLI
Installation	Complex	pip install
Automation	Limited	First-class

📦 Installation Details

The install script will:

1. ✅ Check Python and pip
2. ✅ Install codrninja from PyPI or git
3. ✅ Install Rich (optional, for TUI)
4. ✅ Add ~/.local/bin to PATH
5. ✅ Create config directory
6. ✅ Install codrninja-setup helper

🔗 Links

• GitHub: https://github.com/20ZollCoder/codrninja
• Issues: https://github.com/20ZollCoder/codrninja/issues

📄 License

MIT