cagent - your custom and customizable agent.

by stepan rutz (https://stepanrutz.com)

License is MIT. See LICENSE for details.

This coding-agent is a TypeScript implementation of an autonomous agent framework that can interact with language models, execute tools, and perform tasks based on user input.

It designed to be simple and modular. Also it is meant to be a starting point for including it into your own projects. Think of shadcn approach and copy it into your projects, just like I do.

Specialities include:

• Add new tools in a modular way (see src/tools/)
• Support for multiple LLM providers (llama.cpp, ollama, OpenAI, Anthropic, Azure, etc.)
• The agent wrote itself for the most part.

Special config files and directories

$HOME/.customagent/

• config.json — global configuration (model, provider, stream, etc.)

• systemconf.jon - file written by the agent to store user settings

• skills/ — directory for agent skills (optional, all Markdown files are loaded as context)

• memory/ — directory for agent memory files (optional, all Markdown files are loaded as context)

• src/agent.ts — main agent logic and REPL

• src/api.ts — LLM API interaction and configuration

• src/tools/ — directory for tool definitions and implementations

Disclaimer

This project is provided "as is", without warranty of any kind, express or implied. It is not intended for production use. The agent executes shell commands, writes files, and interacts with external APIs on your behalf — always review its actions before approving them. The author assumes no responsibility for any damage, data loss, or unintended side effects caused by running this software. Use it at your own risk and in environments where you are comfortable with autonomous code execution.

Author

• Name: Stepan Rutz
• Webpage: https://stepanrutz.com

Setup for users

You must have node.js Version >= 22 installed. Then choose one of the following options:

# install globally with npm (you will be notified about updates. run `cagent` directly from the terminal)
npm install -g cagent
cagent "what tools you got"

# run current version with npx without installing
npx https://github.com/srutz/cagent

To uninstall the global version, run:

npm uninstall -g cagent

Setup for developers

npm install
npm run build

Run

Interactive REPL — ask tasks one at a time:

npx cagent what tools you got

One-shot — pass the task as an argument:

npx cagent "write a python script that finds all prime numbers up to 100"
npx cagent "find and fix bugs in my code, 5 at a time"

Architecture

main()
  ├── one-shot mode  (argv)
  └── REPL mode      (readline)
        └── runAgent(task)
              └── loop (max 20 turns)
                    ├── callLLM(messages)   → fetch /v1/messages
                    ├── print text blocks
                    ├── if stop_reason === "end_turn" → done
                    └── if stop_reason === "tool_use"
                          ├── executeTool(name, input)
                          └── append tool_result → continue

Tool Discovery

The agent supports tool usage for code execution, file I/O, search, queries, and more. Tool discovery works as follows:

• Tools are defined as modules in src/tools/ with a common interface (ToolDefinition).
• Each tool provides a name, description, input schema, and an execute function.
• The array of enabled tools is managed in src/tools/index.ts.
• When a tool call is needed (as decided by the LLM), the agent will match the requested tool name against this set.
• Tool metadata (name/description/schema) is sent to the LLM to enable autonomous tool invocation.
• To add a tool, create a new module in src/tools/, implement the ToolDefinition interface, and add it to the definitions array in src/tools/index.ts.

This design allows the agent to dynamically discover capabilities at launch, exposing all declared tools for use in code generation, REPLs, and more.

To add a tool to the agent, simply create a new file in src/tools/ that exports a ToolDefinition object. Also make sure to add the tool to the definitions array in src/tools/index.ts so that it is included in the agent's capabilities.