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:

1. ~/.config/crystal_agent/config.json
2. ~/.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