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: 🚧 Early Development (v0.1.0 Foundation)

Core infrastructure is ready. Active development in progress.

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

Planned Features

18 LLM Tools

Category	Tools	Status
Read	get_lines, get_function, get_class, get_structure	🔜 v0.5.0
Edit	edit_lines, create_file, delete_file	🔜 v0.6.0
Search	find_references, find_definition	🔜 v0.7.0
Analysis	get_dependencies, get_dependents, get_complexity, get_todos	🔜 v0.8.0
Git	git_status, git_diff, git_commit	🔜 v0.9.0
Run	run_command, run_tests	🔜 v0.9.0

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                     │
├───────────────────────────────────────────────────────────┤
│ > _                                                       │
└───────────────────────────────────────────────────────────┘

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

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)

• Project setup (tsup, vitest, ESM)
• Domain entities (Session, Project)
• Value objects (FileData, FileAST, ChatMessage, etc.)
• Service interfaces (IStorage, ILLMClient, ITool, IIndexer)
• Shared module (Config, Errors, Utils)
• CLI placeholder commands
• 91 unit tests, 100% coverage

🔜 Next Up

• v0.2.0 - Redis Storage
• v0.3.0 - Indexer (file scanning, AST parsing)
• v0.4.0 - LLM Integration (Ollama)
• v0.5.0-0.9.0 - Tools implementation
• v0.10.0 - Session management
• v0.11.0 - TUI

See ROADMAP.md for detailed development plan.

API (Coming Soon)

import { startSession, handleMessage } from "@samiyev/ipuaro"

// Start a session
const session = await startSession({
    projectPath: "./my-project",
    model: "qwen2.5-coder:7b-instruct"
})

// Send a message
const response = await handleMessage(session, "Explain the auth flow")

console.log(response.content)
console.log(`Tokens: ${response.stats.tokens}`)
console.log(`Tool calls: ${response.stats.toolCalls}`)

How It Works

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 context

Tool-Based Code Access

User: "How does user creation work?"

ipuaro:
1. [get_structure src/] → sees user/ folder
2. [get_function src/user/service.ts createUser] → gets function code
3. [find_references createUser] → finds all usages
4. Synthesizes answer with specific code context

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