puaros/packages/ipuaro

@samiyev/ipuaro 🎩

Local AI Agent for Codebase Operations

"Infinite" context feeling through lazy loading - work with your entire codebase using local LLM.

Status: 🎉 Release Candidate (v0.16.0 → v1.0.0)

All core features complete. Production-ready release coming soon.

Vision

Work with codebases of any size using local AI:

• 📂 Lazy Loading: Load code on-demand, not all at once
• 🧠 Smart Context: AST-based understanding of your code structure
• 🔒 100% Local: Your code never leaves your machine
• ⚡ Fast: Redis persistence + tree-sitter parsing

Features

18 LLM Tools (All Implemented ✅)

Category	Tools	Description
Read	get_lines, get_function, get_class, get_structure	Read code without loading everything into context
Edit	edit_lines, create_file, delete_file	Make changes with confirmation and undo support
Search	find_references, find_definition	Find symbol definitions and usages across codebase
Analysis	get_dependencies, get_dependents, get_complexity, get_todos	Analyze code structure, complexity, and TODOs
Git	git_status, git_diff, git_commit	Git operations with safety checks
Run	run_command, run_tests	Execute commands and tests with security validation

See Tools Documentation below for detailed usage examples.

Terminal UI

┌─ ipuaro ──────────────────────────────────────────────────┐
│ [ctx: 12%] [project: myapp] [main] [47m] ✓ Ready          │
├───────────────────────────────────────────────────────────┤
│ You: How does the authentication flow work?               │
│                                                           │
│ Assistant: Let me analyze the auth module...              │
│ [get_structure src/auth/]                                 │
│ [get_function src/auth/service.ts login]                  │
│                                                           │
│ The authentication flow works as follows:                 │
│ 1. User calls POST /auth/login                            │
│ 2. AuthService.login() validates credentials...           │
│                                                           │
│ ⏱ 3.2s │ 1,247 tokens │ 2 tool calls                     │
├───────────────────────────────────────────────────────────┤
│ > _                                                       │
└───────────────────────────────────────────────────────────┘

Slash Commands

Control your session with built-in commands:

Command	Description
/help	Show all commands and hotkeys
/clear	Clear chat history (keeps session)
/undo	Revert last file change from undo stack
/sessions [list|load|delete] [id]	Manage sessions
/status	Show system status (LLM, context, stats)
/reindex	Force full project reindexation
/eval	LLM self-check for hallucinations
/auto-apply [on|off]	Toggle auto-apply mode for edits

Hotkeys

Hotkey	Action
Ctrl+C	Interrupt generation (1st press) / Exit (2nd press within 1s)
Ctrl+D	Exit and save session
Ctrl+Z	Undo last file change
↑ / ↓	Navigate input history
Tab	Path autocomplete (coming soon)

Key Capabilities

🔍 Smart Code Understanding

• tree-sitter AST parsing (TypeScript, JavaScript)
• Symbol index for fast lookups
• Dependency graph analysis

💾 Persistent Sessions

• Redis storage with AOF persistence
• Session history across restarts
• Undo stack for file changes

🛡️ Security

• Command blacklist (dangerous operations blocked)
• Command whitelist (safe commands auto-approved)
• Path validation (no access outside project)

Installation

npm install @samiyev/ipuaro
# or
pnpm add @samiyev/ipuaro

Requirements

• Node.js >= 20.0.0
• Redis (for persistence)
• Ollama (for local LLM inference)

Setup Ollama

# Install Ollama (macOS)
brew install ollama

# Start Ollama
ollama serve

# Pull recommended model
ollama pull qwen2.5-coder:7b-instruct

Setup Redis

# Install Redis (macOS)
brew install redis

# Start Redis with persistence
redis-server --appendonly yes

Usage

# Start ipuaro in current directory
ipuaro

# Start in specific directory
ipuaro /path/to/project

# With custom model
ipuaro --model qwen2.5-coder:32b-instruct

# With auto-apply mode (skip edit confirmations)
ipuaro --auto-apply

Quick Start

Try ipuaro with our demo project:

# Navigate to demo project
cd examples/demo-project

# Install dependencies
npm install

# Start ipuaro
npx @samiyev/ipuaro

See examples/demo-project for detailed usage guide and example conversations.

Commands

Command	Description
ipuaro [path]	Start TUI in directory
ipuaro init	Create .ipuaro.json config
ipuaro index	Index project without TUI

Configuration

Create .ipuaro.json in your project root:

{
    "redis": {
        "host": "localhost",
        "port": 6379
    },
    "llm": {
        "model": "qwen2.5-coder:7b-instruct",
        "temperature": 0.1
    },
    "project": {
        "ignorePatterns": ["node_modules", "dist", ".git"]
    },
    "edit": {
        "autoApply": false
    }
}

Architecture

Clean Architecture with clear separation:

@samiyev/ipuaro/
├── domain/              # Business logic (no dependencies)
│   ├── entities/        # Session, Project
│   ├── value-objects/   # FileData, FileAST, ChatMessage, etc.
│   └── services/        # IStorage, ILLMClient, ITool, IIndexer
├── application/         # Use cases & orchestration
│   ├── use-cases/       # StartSession, HandleMessage, etc.
│   └── interfaces/      # IToolRegistry
├── infrastructure/      # External implementations
│   ├── storage/         # Redis client & storage
│   ├── llm/             # Ollama client & prompts
│   ├── indexer/         # File scanner, AST parser
│   └── tools/           # 18 tool implementations
├── tui/                 # Terminal UI (Ink/React)
│   └── components/      # StatusBar, Chat, Input, etc.
├── cli/                 # CLI entry point
└── shared/              # Config, errors, utils

Development Status

✅ Completed (v0.1.0 - v0.16.0)

• v0.1.0 - v0.4.0: Foundation (domain, storage, indexer, LLM integration)
• v0.5.0 - v0.9.0: All 18 tools implemented
• v0.10.0: Session management with undo support
• v0.11.0 - v0.12.0: Full TUI with all components
• v0.13.0: Security (PathValidator, command validation)
• v0.14.0: 8 slash commands
• v0.15.0: CLI entry point with onboarding
• v0.16.0: Comprehensive error handling system
• 1420 tests, 98% coverage

🔜 v1.0.0 - Production Ready

• Performance optimizations
• Complete documentation
• Working examples

See ROADMAP.md for detailed development plan and CHANGELOG.md for release history.

Tools Reference

The AI agent has access to 18 tools for working with your codebase. Here are the most commonly used ones:

Read Tools

get_lines(path, start?, end?) Read specific lines from a file.

You: Show me the authentication logic
Assistant: [get_lines src/auth/service.ts 45 67]
# Returns lines 45-67 with line numbers

get_function(path, name) Get a specific function's source code and metadata.

You: How does the login function work?
Assistant: [get_function src/auth/service.ts login]
# Returns function code, params, return type, and metadata

get_class(path, name) Get a specific class's source code and metadata.

You: Show me the UserService class
Assistant: [get_class src/services/user.ts UserService]
# Returns class code, methods, properties, and inheritance info

get_structure(path?, depth?) Get directory tree structure.

You: What's in the src/auth directory?
Assistant: [get_structure src/auth]
# Returns ASCII tree with files and folders

Edit Tools

edit_lines(path, start, end, content) Replace lines in a file (requires confirmation).

You: Update the timeout to 5000ms
Assistant: [edit_lines src/config.ts 23 23 "  timeout: 5000,"]
# Shows diff, asks for confirmation

create_file(path, content) Create a new file (requires confirmation).

You: Create a new utility for date formatting
Assistant: [create_file src/utils/date.ts "export function formatDate..."]
# Creates file after confirmation

delete_file(path) Delete a file (requires confirmation).

You: Remove the old test file
Assistant: [delete_file tests/old-test.test.ts]
# Deletes after confirmation

Search Tools

find_references(symbol, path?) Find all usages of a symbol across the codebase.

You: Where is getUserById used?
Assistant: [find_references getUserById]
# Returns all files/lines where it's called

find_definition(symbol) Find where a symbol is defined.

You: Where is ApiClient defined?
Assistant: [find_definition ApiClient]
# Returns file, line, and context

Analysis Tools

get_dependencies(path) Get files that a specific file imports.

You: What does auth.ts depend on?
Assistant: [get_dependencies src/auth/service.ts]
# Returns list of imported files

get_dependents(path) Get files that import a specific file.

You: What files use the database module?
Assistant: [get_dependents src/db/index.ts]
# Returns list of files importing this

get_complexity(path?, limit?) Get complexity metrics for files.

You: Which files are most complex?
Assistant: [get_complexity null 10]
# Returns top 10 most complex files with metrics

get_todos(path?, type?) Find TODO/FIXME/HACK comments.

You: What TODOs are there?
Assistant: [get_todos]
# Returns all TODO comments with locations

Git Tools

git_status() Get current git repository status.

You: What files have changed?
Assistant: [git_status]
# Returns branch, staged, modified, untracked files

git_diff(path?, staged?) Get uncommitted changes.

You: Show me what changed in auth.ts
Assistant: [git_diff src/auth/service.ts]
# Returns diff output

git_commit(message, files?) Create a git commit (requires confirmation).

You: Commit these auth changes
Assistant: [git_commit "feat: add password reset flow" ["src/auth/service.ts"]]
# Creates commit after confirmation

Run Tools

run_command(command, timeout?) Execute shell commands (with security validation).

You: Run the build
Assistant: [run_command "npm run build"]
# Checks security, then executes

run_tests(path?, filter?, watch?) Run project tests.

You: Test the auth module
Assistant: [run_tests "tests/auth" null false]
# Auto-detects test runner and executes

For complete tool documentation with all parameters and options, see TOOLS.md.

Programmatic API

You can use ipuaro as a library in your own Node.js applications:

import {
    createRedisClient,
    RedisStorage,
    OllamaClient,
    ToolRegistry,
    StartSession,
    HandleMessage
} from "@samiyev/ipuaro"

// Initialize dependencies
const redis = await createRedisClient({ host: "localhost", port: 6379 })
const storage = new RedisStorage(redis, "my-project")
const llm = new OllamaClient({
    model: "qwen2.5-coder:7b-instruct",
    contextWindow: 128000,
    temperature: 0.1
})
const tools = new ToolRegistry()

// Register tools
tools.register(new GetLinesTool(storage, "/path/to/project"))
// ... register other tools

// Start a session
const startSession = new StartSession(storage)
const session = await startSession.execute("my-project")

// Handle a message
const handleMessage = new HandleMessage(storage, llm, tools)
await handleMessage.execute(session, "Show me the auth flow")

// Session is automatically updated in Redis

For full API documentation, see the TypeScript definitions in src/ or explore the source code.

How It Works

1. Project Indexing

When you start ipuaro, it scans your project and builds an index:

1. File Scanner → Recursively scans files (.ts, .js, .tsx, .jsx)
2. AST Parser → Parses with tree-sitter (extracts functions, classes, imports)
3. Meta Analyzer → Calculates complexity, dependencies, hub detection
4. Index Builder → Creates symbol index and dependency graph
5. Redis Storage → Persists everything for instant startup next time
6. Watchdog → Watches files for changes and updates index in background

2. Lazy Loading Context

Instead of loading entire codebase into context:

Traditional approach:
├── Load all files → 500k tokens → ❌ Exceeds context window

ipuaro approach:
├── Load project structure → ~2k tokens
├── Load AST metadata → ~10k tokens
├── On demand: get_function("auth.ts", "login") → ~200 tokens
├── Total: ~12k tokens → ✅ Fits in 128k context window

Context automatically compresses when usage exceeds 80% by summarizing old messages.

3. Tool-Based Code Access

The LLM doesn't see your code initially. It only sees structure and metadata. When it needs code, it uses tools:

You: "How does user creation work?"

Agent reasoning:
1. [get_structure src/] → sees user/ folder exists
2. [get_function src/user/service.ts createUser] → loads specific function
3. [find_references createUser] → finds all usages
4. Synthesizes answer with only relevant code loaded

Total tokens used: ~2k (vs loading entire src/ which could be 50k+)

4. Session Persistence

Everything is saved to Redis:

• Chat history and context state
• Undo stack (last 10 file changes)
• Session metadata and statistics

Resume your session anytime with /sessions load <id>.

5. Security Model

Three-layer security:

1. Blacklist: Dangerous commands always blocked (rm -rf, sudo, etc.)
2. Whitelist: Safe commands auto-approved (npm, git status, etc.)
3. Confirmation: Unknown commands require user approval

File operations are restricted to project directory only (path traversal prevention).

Troubleshooting

Redis Connection Errors

Error: Redis connection failed

Solutions:

# Check if Redis is running
redis-cli ping  # Should return "PONG"

# Start Redis with AOF persistence
redis-server --appendonly yes

# Check Redis logs
tail -f /usr/local/var/log/redis.log  # macOS

Ollama Model Not Found

Error: Model qwen2.5-coder:7b-instruct not found

Solutions:

# Pull the model
ollama pull qwen2.5-coder:7b-instruct

# List installed models
ollama list

# Check Ollama is running
ollama serve

Large Project Performance

Issue: Indexing takes too long or uses too much memory

Solutions:

# Index only a subdirectory
ipuaro ./src

# Add more ignore patterns to .ipuaro.json
{
    "project": {
        "ignorePatterns": ["node_modules", "dist", ".git", "coverage", "build"]
    }
}

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" ipuaro

Context Window Exceeded

Issue: Context window exceeded errors

Solutions:

• Context auto-compresses at 80%, but you can manually /clear history
• Use more targeted questions instead of asking about entire codebase
• The agent will automatically use tools to load only what's needed

File Changes Not Detected

Issue: Made changes but agent doesn't see them

Solutions:

# Force reindex
/reindex

# Or restart with fresh index
rm -rf ~/.ipuaro/cache
ipuaro

Undo Not Working

Issue: /undo says no changes to undo

Explanation: Undo stack only tracks the last 10 file edits made through ipuaro. Manual file edits outside ipuaro cannot be undone.

FAQ

Q: Does ipuaro send my code to any external servers?

A: No. Everything runs locally. Ollama runs on your machine, Redis stores data locally, and no network requests are made except to your local Ollama instance.

Q: What languages are supported?

A: Currently TypeScript, JavaScript (including TSX/JSX). More languages planned for future versions.

Q: Can I use OpenAI/Anthropic/other LLM providers?

A: Currently only Ollama is supported. OpenAI/Anthropic support is planned for v1.2.0.

Q: How much disk space does Redis use?

A: Depends on project size. A typical mid-size project (1000 files) uses ~50-100MB. Redis uses AOF persistence, so data survives restarts.

Q: Can I use ipuaro in a CI/CD pipeline?

A: Yes, but it's designed for interactive use. For automated code analysis, consider the programmatic API.

Q: What's the difference between ipuaro and GitHub Copilot?

A: Copilot is an autocomplete tool. ipuaro is a conversational agent that can read, analyze, modify files, run commands, and has full codebase understanding through AST parsing.

Q: Why Redis instead of SQLite or JSON files?

A: Redis provides fast in-memory access, AOF persistence, and handles concurrent access well. The session model fits Redis's data structures perfectly.

Contributing

Contributions welcome! This project is in early development.

# Clone
git clone https://github.com/samiyev/puaros.git
cd puaros/packages/ipuaro

# Install
pnpm install

# Build
pnpm build

# Test
pnpm test:run

# Coverage
pnpm test:coverage

License

MIT © Fozilbek Samiyev

Links

• GitHub Repository
• Issues
• Changelog
• Roadmap