Genesys Agent CLI

Summary

The Genesys Agent CLI (@gnsx/genesys.agent.cli) is a command-line interface for interacting with AI-powered development agents. It provides an intelligent code assistant that can help with various development tasks through natural language conversations.

Key Features

• Multi-Provider Support: Works with multiple LLM providers including Anthropic Claude, OpenAI GPT, DeepSeek, Groq, xAI, Kimi, and more
• Flexible Configuration: Use YAML-based agent specifications to customize behavior, tools, and model selection
• Chat Persistence: Automatically saves conversation history, allowing you to resume sessions using chat IDs
• Tool Integration: Extensive tool capabilities including:
  • File operations (read, edit, list)
  • Code search (grep, glob patterns)
  • Terminal command execution
  • Web browsing and search
  • TODO/task management
• MCP Integration: Supports Model Context Protocol for extending agent capabilities with external context providers
• Observability: Built-in support for tracing with LangWatch and Langfuse
• Auto-Updates: Automatic version checking and easy updates via pnpm
• Cost Tracking: Real-time token usage and cost calculation per conversation

Installation

Prerequisites

• Node.js: Version 18 or higher
• pnpm: Install from pnpm.io

Global Installation

Install the CLI globally using pnpm:

pnpm add -g @gnsx/genesys.agent.cli

Verify Installation

After installation, verify that the CLI is available:

genesys --version

You should see the version number displayed.

Environment Setup

Before using the CLI, you'll need to configure API keys for your chosen LLM provider(s) as environment variables.

API Key Format: Environment variable names follow the pattern <PROVIDER>_API_KEY where <PROVIDER> is the uppercase provider name.

Supported Providers:

• Anthropic - Claude models (ANTHROPIC_API_KEY)
• OpenAI - GPT models (OPENAI_API_KEY)
• DeepSeek - DeepSeek models (DEEPSEEK_API_KEY)
• Groq - Fast inference (GROQ_API_KEY)
• xAI - Grok models (XAI_API_KEY)
• OpenRouter - Multi-provider gateway (OPENROUTER_API_KEY)
• Kimi - Moonshot models (KIMI_API_KEY)
• OpenCode - Zen gateway (OPENCODE_API_KEY)
• Xiaomi - Xiaomi models (XIAOMI_API_KEY)
• Ollama - Local deployment (no API key required)

Add these to your shell configuration file (e.g., .bashrc, .zshrc, or .bash_profile) to make them permanent.

Updating

The CLI will automatically check for updates when you run it. When a new version is available, you'll be prompted to update. You can also manually update at any time:

pnpm add -g @gnsx/genesys.agent.cli@latest

Usage

Basic Usage

Run the CLI agent in the current directory:

genesys

Run the CLI agent in a specific project directory:

genesys /path/to/your/project

Command-Line Options

genesys [path] [options]

Arguments:
  path                    Working directory for the agent (defaults to current directory)

Options:
  -V, --version           Display version number
  -h, --help              Display help information
  --spec <file>           Agent configuration YAML spec file (defaults to coder.yaml)
  --model <model>         Override the model specified in the spec file
  --chat-id <id>          Resume an existing chat session
  -p, --prompt <text>     Initial prompt to send to the agent (auto-exits when complete)
  --ui <type>             UI type: "ink" (React-based, default) or "stdout" (console-based)
  --tracing <provider>    Enable OpenTelemetry tracing (e.g., "langwatch", "langfuse")

Usage Examples

Start an interactive session in the current directory:

genesys

Use a specific agent specification:

genesys --spec ui-specialist.yaml

Override the model from the spec file:

genesys --model claude-sonnet-4-5@anthropic

Resume a previous chat session:

genesys --chat-id abc123-def456-789

Run with a one-time prompt (auto-exit mode):

genesys -p "Add error handling to the authentication module"

Use the stdout UI instead of Ink:

genesys --ui stdout

Combine multiple options:

genesys /path/to/project --spec coder.yaml --model gpt-4o@openai --ui ink

Interactive Commands

Once the agent is running, you can use these slash commands:

• /clear - Clear all messages and reset the conversation
• /model - Show an interactive model selector to switch between models from the current provider
• /spec - Show an interactive spec selector to switch to a different agent specification

Chat Persistence

All conversations are automatically saved to the .genesys/chats directory in your project. Each chat has a unique ID that you can use to resume later. The CLI will display the chat ID when you start a session:

Chat ID: abc123-def456-789 (use --chat-id abc123-def456-789 to resume this conversation)

Logs

All logs are automatically saved to the .genesys/logs directory in your working directory. Log files are named based on the session:

• With chat ID: agent-<chat-id>.log - When resuming a session with --chat-id
• New session: agent-<timestamp>.log - When starting a new session

You can configure logging behavior using environment variables:

• CONSOLE_LOG_LEVEL - Console output level: DEBUG, INFO, WARN, ERROR, NONE (default: INFO)
• FILE_LOG_LEVEL - File logging level: DEBUG, INFO, WARN, ERROR, NONE (default: DEBUG)
• DEBUG=true - Shorthand to enable debug level logging for both console and file

Auto-Exit Mode

When you use the -p or --prompt option, the agent will automatically exit after completing the task. This is useful for:

• CI/CD pipelines
• Automated code generation scripts
• One-off tasks without interactive sessions

A report file (agent-report.json) will be generated with statistics including token usage, costs, and execution time.

Agent Specifications

What are Agent Specs?

Agent specifications (specs) are YAML configuration files that define how an AI agent behaves. They control the agent's personality, capabilities, available tools, and interaction patterns. Think of them as "profiles" for different types of development tasks.

Why Use Agent Specs?

Different development tasks require different expertise and approaches:

• General coding needs broad tool access and general problem-solving
• UI development requires specialized knowledge of UI patterns and components
• Backend work may focus on APIs, databases, and server architecture
• Code review needs analytical capabilities without modification permissions

Agent specs let you switch between these specialized configurations instantly without reconfiguring settings.

Configuration Fields

Required Fields

• systemPrompt (string): Defines the agent's personality, expertise, and behavior guidelines. This is the core instruction that shapes how the agent responds.

• model (string): Specifies which AI model to use in the format <model-name>@<provider>. Examples:

  • claude-sonnet-4-5@anthropic
  • gpt-4o@openai
  • google/gemini-3-flash-preview@openrouter

Optional Fields

• name (string): Display name for the agent (e.g., "Coding Agent", "UI Specialist")

• temperature (number): Controls randomness in responses (0.0 = deterministic, 2.0 = creative). Default varies by model.

• topP (number): Nucleus sampling parameter for controlling response diversity

• topK (number): Top-K sampling parameter for limiting token selection

• dynamicContext (string): Runtime information injected as context. Supports placeholders:

  • {systemContext} - OS info, date, workspace path
  • {projectLayout} - Current project directory structure
  • @file:<path> - Include contents of external files

• systemReminder (string): Persistent reminders shown with every tool result

• enabledTools (array): Whitelist of allowed tools. Cannot be used with disabledTools.

• disabledTools (array): Blacklist of forbidden tools. Cannot be used with enabledTools.

Example Agent Spec

name: "Coding Agent"

model: "claude-sonnet-4-5@anthropic"

temperature: 0.0

systemPrompt: |
  You are a highly skilled software development agent with expertise in:
  - Writing clean, maintainable code
  - Following best practices and design patterns
  - Comprehensive testing and documentation
  
  Always explain your reasoning and consider edge cases.

dynamicContext: |
  <system-context>
  {systemContext}
  </system-context>
  
  <project-rules>
  @file:./AGENTS.md
  </project-rules>
  
  <project-layout>
  {projectLayout}
  </project-layout>

systemReminder: |
  Remember to run tests after making changes.

enabledTools:
  - read
  - edit
  - list
  - grep
  - glob
  - terminal

Using Spec Files

Default Spec

By default, the CLI uses coder.yaml from the built-in specs.

Using a Built-in Spec

The CLI includes several pre-configured specs. Specify one with the --spec option:

genesys --spec ui-specialist.yaml
genesys --spec gd-specialist.yaml

Built-in specs:

• coder.yaml - General-purpose coding assistant (default)
• ui-specialist.yaml - UI/UX development expert
• gd-specialist.yaml - Game development specialist

Using a Custom Spec

Create your own spec file in your project directory and reference it:

genesys --spec my-custom-agent.yaml
genesys --spec .genesys/specs/backend-specialist.yaml

The CLI looks for spec files in this order:

1. Your project directory (relative to working directory)
2. Built-in specs (from the CLI package)

Switching Specs During a Session

Use the /spec slash command to interactively switch between built-in specs:

/spec

This displays a list of all built-in specs with their names and models. Note: Custom specs from your project directory are not shown in this list, but can still be used with the --spec option when starting the CLI.

Creating Custom Specs

1. Create a new YAML file in your project directory (recommended: .genesys/specs/ folder)
2. Define required fields (systemPrompt, model)
3. Add optional configuration as needed
4. Run the CLI with genesys --spec path/to/your-spec.yaml

Example directory structure:

your-project/
├── .genesys/
│   └── specs/
│       ├── backend-agent.yaml
│       └── reviewer-agent.yaml
├── src/
└── ...

Tips for creating specs:

• Keep system prompts focused and specific
• Use dynamicContext for runtime information
• Use @file: references to include shared rules or documentation
• Test different temperature settings to find the right balance
• Use tool filtering to restrict capabilities for specialized tasks
• Store custom specs in .genesys/specs/ for organization

Available Tools

The agent has access to a comprehensive set of tools for development tasks. Tools can be controlled via agent spec configuration using enabledTools or disabledTools fields.

Core Tools

• read - Read file contents with optional line range selection. Supports reading any file on the filesystem.

• edit - Modify files using find-and-replace operations. Creates new files if they don't exist. Supports replaceAll for renaming variables across files.

• list - List files and directories at a given path. Respects .gitignore and .cursorignore patterns by default.

• grep - Powerful code search using ripgrep. Supports regex patterns, context lines, file type filtering, and multiple output modes (content, files, count).

• glob - Fast file pattern matching for finding files by name patterns (e.g., **/*.js, src/**/*.ts). Works efficiently with large codebases.

• terminal - Execute shell commands and scripts. Supports working directory specification and timeout configuration.

Productivity Tools

• todo - Create and manage task lists within your session. Helps track progress and organize complex multi-step tasks.

• task - Launch specialized sub-agents for complex, autonomous tasks. Delegates work to focused agents with specific toolsets.

Web Tools

• web_search - Search the web using Tavily API. Provides up-to-date information for current events and recent data. Supports domain filtering.

• web_fetch - Fetch and extract content from URLs. Converts HTML to markdown and optionally processes content with AI.

Tool Configuration

Control tool availability in your agent spec:

# Whitelist specific tools only
enabledTools:
  - read
  - edit
  - grep
  - terminal

# Or blacklist specific tools
disabledTools:
  - web_search
  - web_fetch

Note: You cannot use both enabledTools and disabledTools simultaneously.