AGI CLI Agent

AGI is an interactive terminal agent powered by OpenAI, DeepSeek, or OpenRouter. It streams responses, keeps multi-turn conversation history for the current session, and can use filesystem, shell, date/time, and web-search tools with human approval.

The agent loop and model integrations use the Vercel AI SDK.

The project is created for educational purpose and was inspired by https://github.com/Hendrixer/agents-v2 course.

Features

• OpenAI, DeepSeek, and OpenRouter model providers
• Configurable model selection through environment variables
• Streaming responses and session-scoped conversation history
• Context usage estimation and automatic conversation compaction
• Explicit approval before every tool execution
• Valid model history for both approved and rejected tool calls
• Editable terminal input with cursor navigation
• Optional Laminar telemetry and evaluation scripts

Requirements

• Node.js 20 or later
• npm
• An API key for OpenAI, DeepSeek, or OpenRouter

Installation

Install dependencies and build the CLI:

npm install
npm run build

Run it directly from the repository:

npm run start

Or install the agi command globally:

npm install -g .
agi

Run agi from the directory in which you want the agent to operate. Local filesystem and shell tools use that directory as their working context.

Provider configuration

Create a .env file in the directory from which you start the agent.

Provider	AI_PROVIDER	Required key	Default model	API mode
OpenAI	openai	OPENAI_API_KEY	gpt-5.4-mini	OpenAI Responses API
DeepSeek	deepseek	DEEPSEEK_API_KEY	deepseek-v4-flash	OpenAI-compatible Chat Completions
OpenRouter	openrouter	OPENROUTER_API_KEY	openrouter/auto	OpenAI-compatible Chat Completions

AI_MODEL overrides the default model for the selected provider. Invalid providers and missing provider-specific keys are reported before a model request is made.

OpenAI

OpenAI is the default provider:

AI_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key

# Optional; defaults to gpt-5.4-mini
# AI_MODEL=gpt-5.4-mini

DeepSeek

DeepSeek uses its OpenAI-compatible Chat Completions API:

AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=your_deepseek_api_key

# Optional; defaults to deepseek-v4-flash
# AI_MODEL=deepseek-v4-pro

OpenRouter

OpenRouter provides an OpenAI-compatible API at https://openrouter.ai/api/v1 for routed or explicitly selected models:

AI_PROVIDER=openrouter
OPENROUTER_API_KEY=your_openrouter_api_key

# Optional; defaults to openrouter/auto
# AI_MODEL=anthropic/claude-sonnet-4.5

When local tools are needed, choose an OpenRouter model that supports tool calling. openrouter/auto lets OpenRouter select a model for each request; AI_MODEL accepts explicit OpenRouter slugs such as anthropic/claude-sonnet-4.5.

Telemetry

Laminar telemetry is optional:

LMNR_PROJECT_API_KEY=your_laminar_project_api_key

See .env.example for the complete configuration template.

Using the CLI

Enter a prompt after >. Model output is displayed as it streams. Type exit or quit to close the application.

Input editing supports:

Key	Action
Left / Right	Move the cursor
Backspace	Delete before the cursor
Ctrl+D	Delete at the cursor
Ctrl+A / Ctrl+E	Move to the start / end
Ctrl+B / Ctrl+F	Move backward / forward
Enter	Submit the prompt

When the model requests a tool, the CLI displays its name and arguments. Use Up/Down to select Yes or No, then press Enter. A rejected call is reported back to the model without executing the tool.

Tools

Tool	Availability	Description
dateTime	All providers	Returns the current date and time.
readFile	All providers	Reads a UTF-8 file.
listFiles	All providers	Lists files and directories at a path.
writeFile	All providers	Creates or overwrites a file and creates missing parent directories.
deleteFile	All providers	Permanently deletes a file.
runCommand	All providers	Executes a shell command and returns its output.
webSearch	OpenAI only	Uses OpenAI's provider-hosted web search.

DeepSeek and OpenRouter modes exclude webSearch because the current tool is hosted by OpenAI rather than implemented locally. OpenRouter-specific server-side web search is not yet integrated.

Safety

The agent asks for approval before each tool execution in the interactive CLI, but approved tools are not sandboxed:

• Filesystem paths resolve from the process working directory and can point outside the repository.
• writeFile overwrites existing content.
• deleteFile is irreversible.
• runCommand executes commands through the local shell.

Review the displayed tool name and arguments before approving. Run the CLI only in an environment where you are comfortable granting those capabilities.

How it works

The agent uses a manual streaming tool loop:

1. Add the user prompt to filtered conversation history.
2. Compact older history if context usage crosses the configured threshold.
3. Stream a response from the selected model.
4. Collect requested tool calls and ask for approval.
5. Execute approved calls sequentially and record results for every call.
6. Send the results back to the model and continue until it produces a final response.

The same configured provider and model are used for both normal responses and conversation compaction.

Project structure

src/
├── cli.ts                         Installed CLI entry point
├── index.ts                       Development entry point
├── types.ts                       Shared types
├── agent/
│   ├── run.ts                     Streaming agent and tool loop
│   ├── modelProvider.ts           Provider configuration and model factory
│   ├── executeTools.ts            Tool execution dispatcher
│   ├── context/                   Token estimation, limits, and compaction
│   ├── system/                    System prompt and message filtering
│   └── tools/                     Tool definitions
└── ui/
    ├── App.tsx                    Terminal application state
    └── components/                Input, approval, message, and status views

evals/                             Laminar evaluation definitions and data
openspec/                          Project specifications and change proposals

Development

Command	Description
npm run start	Run the TypeScript source with .env configuration.
npm run dev	Run with file watching and automatic restart.
npm test	Run all Node.js tests.
npm run build	Compile the distributable CLI into dist/.
npm run eval	Run Laminar evaluations.
npm run eval:file-tools	Evaluate filesystem tools.
npm run eval:shell-tools	Evaluate shell-tool behavior.
npm run eval:agent	Evaluate multi-turn agent behavior.

The codebase uses TypeScript strict mode, ES modules, Biome, React, Zod, and the Vercel AI SDK.

Roadmap

Planned improvements and open ideas are tracked in ROADMAP.md. The current priorities are provider-neutral web search, safer tool execution, persistent conversations, and broader agent-loop testing.