---

CLI Agent

This repository contains a command-line AI agent (agi) built with TypeScript and powered by the lmnr framework and the AI/OpenAI SDKs. The project provides a CLI entrypoint, evaluation scripts, and examples for using shell/file tools and multi-turn agents.

---

Quick overview

• Project name: agi
• CLI binary (after build): dist/cli.js (exposed as the agi bin in package.json)
• Primary source: src/ (TypeScript)
• Built output: dist/
• Evaluations and tests: evals/

Directory structure

Top-level files and folders you will commonly use:

• .claude/ - (project-specific metadata/config for Claude integrations, if any)
• .env - environment variables (API keys). DO NOT commit this file. Create your own .env locally.
• .gitignore - files and patterns ignored by git (includes .env and dist/)
• AGENTS.md - documentation / configuration for agents shipped with the repo
• CLAUDE.md - notes or configuration related to Claude usage
• biome.json - developer/tooling config (biome formatter/runner)
• course.yaml - optional course/config data used by the project
• dist/ - compiled JavaScript output (generated by npm run build)
• evals/ - evaluation scripts (multi-turn, file-tools, shell-tools, etc.)
• node_modules/ - installed npm dependencies
• notes/ - project notes and scratch files
• openspec/ - open API specs or similar artifacts
• package.json - npm package metadata and scripts (see "Scripts" below)
• package-lock.json - npm lock file
• src/ - TypeScript source code (entrypoint is src/index.ts)
• tsconfig.build.json - TypeScript build configuration used for npm run build
• tsconfig.json - TypeScript config

If you need a specific file's purpose, check that file; the repo already includes AGENTS.md and CLAUDE.md which explain agent-specific config and usage in greater detail.

What the agent can do

This repository implements a CLI AI agent scaffold which typically supports the following capabilities (actual capabilities depend on the code in src/ and available tool registrations):

• Run as a CLI application (development mode or built JS in dist/).

• Use language models via @ai-sdk/openai, ai, and the @lmnr-ai/lmnr framework.

• Execute shell commands and interact with the filesystem via tools (dependencies include shelljs).

• Run automated evaluations contained in evals/ (examples for multi-turn conversations, file-tools, and shell-tools exist).

• Be extended with additional tools, agents, and evaluation scripts by modifying src/ and evals/.

Note: The exact feature set and tools are implemented in src/. Inspect that folder to see how tools are registered and how agents are configured.

Prerequisites

• Node.js (recommended: 18+)
• npm
• API keys for the model providers you intend to use (OpenAI, LMNR project keys, etc.)

Important: put your secrets in a local .env file (the code uses dotenv). Do not commit .env to the repository. If you accidentally commit secret keys, rotate them immediately.

---

Installation

1. Install dependencies: npm install

2. Create a .env in the project root with at least the API keys you need. Example (DO NOT copy/paste real keys you find in repos or screenshots): OPENAI_API_KEY=sk-... LMNR_PROJECT_API_KEY=...

3. (Optional) Build the project to JavaScript: npm run build

Running the agent

• Development (TypeScript with watch): npm run dev This runs tsx watch --env-file=.env src/index.ts so you can iterate quickly.

• Start (one-off run without building): npm start

• Production / built CLI: npm run build npm install -g agi # this runs the production build of the agent

Running evaluations

There are several npm scripts that run evaluation suites (these use npx lmnr eval):

• npm run eval # run default evaluation
• npm run eval:multi-turn # run multi-turn eval example
• npm run eval:file-tools # run file-tools eval script
• npm run eval:shell-tools # run shell-tools eval script
• npm run eval:agent # run agent multi-turn eval

Check evals/ for the TypeScript evaluation files; you can add new eval scripts and wire them into package.json as needed.

How to extend or modify the agent

• Add new tools: implement the tool in src/ (suggested src/tools/), register it with the agent initialization code.
• Add or adjust agents: update AGENTS.md and src/ to define agent behaviors, prompts, and tool access policies.
• Add tests/evaluations: put new eval files in evals/ and add an npm script to run them.
• Build and test locally: use npm run dev during development, npm run build for production.

---

Security and best practices

• Keep .env and other secret-bearing files out of git (this repo's .gitignore already excludes .env).
• Rotate API keys if you believe they were exposed.
• Use least-privilege API keys for development when possible.

Troubleshooting

• "Missing API key" errors: verify your .env contains the expected variables and that you restarted the dev server after editing .env.
• Build/type errors: ensure you are using a recent Node.js version and that dependencies are installed (npm install).

Contributing

Contributions are welcome. Typical workflow:

1. Fork the repo
2. Create a feature branch
3. Add/modify code and tests/evals
4. Run npm run dev or npm run build to verify changes
5. Open a PR describing your changes