package

github.com/alexkutsan/agentish

main / published May 10, 2026 / repository

Agentish - CLI for AI agents with MCP (Model Context Protocol) support. Built on top of AgentKit library.

Agentish

CLI for AI agents with MCP (Model Context Protocol) server support.

Built on top of AgentKit library.

Installation

Requirements

Crystal >= 1.19.0
OpenAI API key (or compatible provider)

Build from source

git clone https://github.com/alexkutsan/agentish.git
cd agentish
shards install
shards build --release

Binary will be at ./bin/agentish.

Quick Start

1. Create configuration

mkdir -p ~/.config/agentish
cat > ~/.config/agentish/config.json << 'EOF'
{
  "openaiApiKey": "sk-your-api-key-here",
  "openaiModel": "gpt-4o"
}
EOF

2. Run the agent

./bin/agentish -p "Hello! How are you?"

Usage

# Direct prompt
./bin/agentish -p "Your question"

# Prompt from file
./bin/agentish prompt.txt

# Output to file
./bin/agentish -p "Generate a list" -o result.txt

# Interactive mode
./bin/agentish -i

# Specify config
./bin/agentish -p "Question" -c /path/to/config.json

Options

Option	Description
`-p, --prompt`	Prompt text
`-o, --output`	Output file (default: stdout)
`-c, --config`	Config file path
`-i, --interactive`	Interactive mode (REPL)
`-h, --help`	Show help
`-v, --version`	Show version

Configuration

Agent looks for config in:

~/.config/crystal_agent/config.json
~/.crystal_agent.json

Minimal config

{
  "openaiApiKey": "sk-..."
}

Full config

{
  "openaiApiKey": "sk-...",
  "openaiApiHost": "https://api.openai.com",
  "openaiModel": "gpt-4o",
  "maxIterations": 10,
  "timeoutSeconds": 120,
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Parameter	Description	Default
`openaiApiKey`	API key (required)	—
`openaiApiHost`	API URL	`https://api.openai.com`
`openaiModel`	Model	`gpt-4o`
`maxIterations`	Max iterations	`10`
`timeoutSeconds`	Timeout (sec)	`120`
`mcpServers`	MCP servers	`{}`

Logging is configured via ENV: CRYSTAL_AGENT_LOG_LEVEL (debug/info/warn/error, default warn) and CRYSTAL_AGENT_LOG_FILE.

MCP Servers

Agent can connect to MCP servers to use external tools.

HTTP config without "type": "http" is considered invalid. Environment variables can be used as ${VAR} or ${VAR:-default}.

{
  "openaiApiKey": "sk-...",
  "mcpServers": {
    "filesystem": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    },
    "database": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Stdio MCP server (local process)

{
  "openaiApiKey": "sk-...",
  "mcpServers": {
    "local-tools": {
      "command": "python3",
      "args": ["-u", "/path/to/mcp_server.py"]
    }
  }
}

On startup, the agent automatically connects to servers and registers available tools.

Documentation

USER_GUIDE.md — detailed user guide
AgentKit — library documentation

License

MIT

API

Agentish