AGI Core

A powerful AI-powered CLI assistant for software engineering. Chat with AI, execute tools, edit files, run commands, and automate complex development tasks - all from your terminal.

Features

• Interactive Chat - Conversational AI interface with streaming responses
• Tool Execution - Read/write/edit files, execute commands, search code
• Git Integration - Built-in git status, diff, commit, branch management
• Auto-Run Mode - AI autonomously completes multi-step tasks
• Session Persistence - Resume conversations across sessions
• Retry Logic - Automatic retry with exponential backoff for reliability

Installation

# Install globally
npm install -g agi-core

# Or install from source
git clone https://github.com/your-org/agi-core.git
cd agi-core
npm install
npm run build
npm link

Requirements: Node.js 20.0.0+

Quick Start

# Set your API key
export OPENAI_API_KEY=your_key_here

# Start interactive mode
agi

# Quick one-shot query
agi -q "explain this error" < error.log

Commands

Chat & Configuration

| Command | Description | |---------|-------------| | /key <key> | Set OpenAI API key | | /model <name> | Switch AI model (gpt-4o, gpt-4, etc.) | | /clear | Clear conversation history | | /history | View/manage conversation history | | /c | Toggle auto-run mode |

Information

| Command | Description | |---------|-------------| | /help | Show all commands | | /status | System status | | /stats | Session statistics | | /tools | List available AI tools |

Session

| Command | Description | |---------|-------------| | /toggle <mode> | Toggle stream/verbose/autosave | | exit / quit / q | Exit CLI |

AI Tools

The AI has access to these tools for completing tasks:

File Operations

• read_file - Read file contents
• write_file - Create or overwrite files
• edit_file - Make precise text replacements
• list_directory - List directory contents
• search_files - Search by filename or content

Code Search

• grep_search - Regex pattern search
• find_definition - Find function/class definitions

Execution

• execute_command - Run shell commands (with safety checks)

Git

• git_status - View modified/staged/untracked files
• git_diff - Show file changes
• git_log - View commit history
• git_commit - Stage and commit changes
• git_branch - Manage branches

Web

• web_search - Search the web
• fetch_url - Fetch URL content

Modes

Stream Mode (default: on)

Displays AI responses character-by-character as they're generated.

Auto-Run Mode (default: on)

When enabled, the AI will automatically continue executing tasks until completion without waiting for user input. Toggle with /c.

Verbose Mode (default: off)

Shows additional details like response timing and tool result previews.

AutoSave Mode (default: off)

Automatically saves conversation history after each exchange.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+C | Interrupt / Exit | | Ctrl+D | Exit | | Ctrl+L | Clear screen | | ↑ / ↓ | Navigate command history |

Session Persistence

AGI Core automatically saves and restores your conversation:

• Sessions persist for 24 hours within the same workspace
• Use /history save to manually save
• Use /history clear to clear saved history
• Use /clear to start a fresh conversation

When resuming a session, you'll see:

↻ Resumed session with X previous messages
Use /clear to start fresh or /history to see details

Error Handling

AGI Core includes intelligent error handling:

• Automatic Retry - Retries on rate limits (429), server errors (5xx), and network issues
• Exponential Backoff - Waits progressively longer between retries
• Recovery Suggestions - Provides helpful tips when errors occur

Configuration

Configuration is stored in ~/.agi/:

~/.agi/
├── config.json    # API keys, model preferences, mode settings
└── history.json   # Saved conversation history

CLI Options

agi [options]

Options:
  -v, --version     Show version
  -h, --help        Show help
  -q, --quick       Quick mode (non-interactive single query)
  --model <name>    Select model
  --advanced        Enable advanced features

Examples

Code Editing

❯ read the main.ts file and fix any TypeScript errors

Git Operations

❯ check git status and commit all changes with a descriptive message

Code Search

❯ find all files that import the UserService class

File Operations

❯ create a new React component called Button in src/components

Command Execution

❯ run the tests and fix any failures

Development

# Build
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Clean build
npm run clean

Project Structure

src/
├── bin/
│   ├── agi.ts      # Main CLI entry point
│   └── ui.ts       # UI components and theming
├── core/
│   └── agi.ts      # Core AGI framework
├── tools/
│   └── execution.ts # Command execution utilities
└── __tests__/      # Test suites

License

MIT

AGI Core - AI-powered development from your terminal