nexus-ai-agent 1.0.1

Intelligent Agentic File Assistant powered by Claude

Nexus - Intelligent Agentic File Assistant

A powerful AI agent powered by Claude that plans and executes complex file operations step-by-step with built-in safety mechanisms.

🎉 Now available on PyPI! Install with: pip install nexus-ai-agent

Features

Agentic Planning

• Automatic Planning: Creates a TODO list before executing tasks
• Step-by-Step Execution: Executes each step methodically
• Loop Detection: Prevents infinite loops and repeated actions
• Adaptive Planning: Adjusts plan if something fails
• Progress Tracking: Shows thinking, progress, and stats

Smart File Operations

• Create/Read/Edit/Delete files with intelligent handling
• Smart Reading: Line ranges, previews, search within files
• Smart Search: Find files by name pattern or content
• Directory Exclusions: Automatically skips .git, node_modules, pycache, etc.
• Token Optimization: 10K character limit prevents token explosion

Safety Mechanisms

• Iteration Limits: Max 15 iterations to prevent runaway
• Loop Detection: Detects and warns about repeated actions
• Action Tracking: Prevents duplicate operations
• Error Handling: Graceful failure with helpful messages

Project Structure

agent/
├── agent.py              # Core agentic logic with planning
├── tools.py              # Tool definitions for Anthropic API
├── tool_functions.py     # Tool implementations
├── examples.py           # Usage examples
├── .env                  # Configuration (API key)
└── README.md            # This file

Quick Start

1. Installation

pip install nexus-ai-agent

Source installation:

git clone https://github.com/Remote-Skills/nexus.git
cd nexus
pip install -e .

2. Configuration

Create a .env file:

ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_MAX_TOKENS=4096

Windows Users: If nexus command doesn't work after installation, your Python Scripts folder may not be in PATH. See Windows CLI Fix Guide or use:

python -m cli "your task"

3. Usage

CLI Mode (Recommended)

# Run a task
nexus "Create a Python web app with Flask"

# Interactive mode
nexus

Note: On Windows, if nexus is not recognized, add Python Scripts to your PATH (see WINDOWS_CLI_FIX.md), or use python -m cli instead.

Python API - Agentic Mode

from agent import chat_with_tools_agentic

# Complex multi-step task with automatic planning
chat_with_tools_agentic(
    "Create a Python project with main.py, requirements.txt, and README.md. "
    "The main.py should have a hello world function."
)

Python API - Simple Mode

from agent import chat_with_tools

# Direct tool usage without planning
chat_with_tools("Create a file called test.txt with hello world")

How It Works

Agentic Mode Flow

User Request
    ↓
1. Agent analyzes task
    ↓
2. Creates TODO listi/plan
    ↓
3. Shows plan to user
    ↓
4. Executes step-by-step
    ↓
5. Checks results
    ↓
6. Adapts if needed
    ↓
7. Final summary

Safety Features

1. Loop Detection: Tracks all actions and prevents repeats
2. Iteration Limit: Max 15 iterations (configurable)
3. Pattern Detection: Warns if same tools used 3+ times
4. Action History: Remembers completed actions

Available Tools

Tool	Description
create_file	Create files with content
read_file	Smart reading with line ranges, search, preview
edit_file	Replace or append content
delete_file	Delete files
list_files	List directory contents (excludes build dirs)
smart_search	Search by filename or content (recursive)

Smart Reading Features

# Preview a large file
"Preview the file 'large_dataset.csv'"

# Read specific lines
"Read lines 100 to 200 from 'app.log'"

# Search within file
"Find all ERROR messages in 'debug.log'"

# Character limit
"Read config.json but limit to 5000 characters"

Example Tasks

Project Creation

chat_with_tools_agentic(
    "Create a Flask web app with proper structure: "
    "app.py, requirements.txt, README.md, and a templates folder"
)

Code Analysis

chat_with_tools_agentic(
    "Analyze all Python files, find TODO comments, "
    "and create a summary in todos.md"
)

Refactoring

chat_with_tools_agentic(
    "Find all files with 'old_function_name' and create a plan "
    "to refactor them to 'new_function_name'"
)

Best Practices

Do:

• Use agentic mode for complex multi-step tasks
• Let the agent create a plan first
• Provide clear, specific task descriptions
• Break down very large tasks into smaller ones

Don't:

• Request tasks that would require >15 iterations
• Ask for operations on extremely large files without using smart reading
• Request recursive operations without clear boundaries

Debugging

The agent shows detailed output:

• Agent Thinking: Planning and reasoning
• Tool Used: Which tool is being called
• Input: Tool parameters
• Result: Tool output
• Stats: Iterations and actions performed

Safety & Limitations

• Iteration Limit: 15 iterations maximum
• File Size: 50KB+ files trigger warnings
• Character Limit: 10K default for reads
• Loop Detection: Prevents infinite loops
• Excluded Dirs: Skips .git, node_modules, etc.

Contributing

Feel free to add new tools or improve the planning logic!

License

MIT License - Feel free to use and modify!