EM Ollama Agent (em-ollama-agent)

A lightweight, cross-platform AI chat CLI and autonomous coding agent by Ethern Myth that communicates directly with your local Ollama models. Works seamlessly across macOS, Linux, and Windows.

Features

• 💬 Fast Conversational Chat Mode (Default): Instant token-by-token streaming for general Q&A, brainstorming, and code explanations without tool overhead.
• 🛠️ Autonomous Agent Mode: Equipped with workspace tools (read_file, write_file, list_directory, search_files, git_diff, run_command) with safety approval policies.
• ⚡ Direct CLI & REPL Support: Use interactively in your terminal or pass one-shot prompts directly via CLI flags.
• 📋 Optional Project Instructions: Automatically discovers and respects agents.md and runners.md files if present.
• 🔒 Security First: Sandboxed to the workspace, protects sensitive files (.env, private keys, credentials), and requires user approval for modifications.
• 📦 Zero Heavy Dependencies: Pure Node.js ESM package.

Requirements

• Node.js: 24.0.0 or higher
• Ollama: Installed and running (ollama serve)
• Local Model: At least one model pulled (e.g., ollama pull qwen2.5-coder, ollama pull llama3.2, ollama pull deepseek-r1)

Installation

Install globally via npm:

npm install -g em-ollama-agent

Or run instantly without installing using npx:

npx em-ollama-agent

Usage

1. Interactive Chat & Agent REPL

Start the interactive terminal interface (starts in Chat Mode by default):

em-ollama
# or
ollama-agent
# or
ollama-cli

To start directly in Agent Mode:

em-ollama --agent
# or
em-ollama -a

Interactive REPL Preview:

========================================
 Ollama CLI v0.1.4
 Workspace:    /path/to/your/project
 Model:        qwen2.5-coder:latest
 Mode:         CHAT (Conversational / fast)
 Instructions: agents.md, runners.md (active)
========================================
Type /help for commands, /agent or /chat to switch modes, /exit to quit.

[chat] > How do I structure unit tests in Node.js?
...
[chat] > /agent
Mode switched to: AGENT (tools and approvals enabled)
[agent] > Inspect src/context.js and add unit tests

2. Direct CLI Prompt Mode (One-Shot)

Run prompts directly from your shell and get streamed output:

Conversational / Q&A Prompt:

em-ollama "Explain the architecture of this repository"

Autonomous Coding Prompt (with tools):

em-ollama -a "Write a unit test for policy.js"

Specify a Custom Model or Endpoint:

em-ollama -m llama3.2 "Help me refactor the database query"
em-ollama --host http://localhost:11434 "What is recursion?"

Project Instructions (agents.md & runners.md)

Instruction files are completely optional and non-mandatory.

When present in your repository, EM Ollama Agent automatically discovers and incorporates them into the context:

• agents.md / AGENTS.md: Project architecture, coding standards, constraints, and guidelines.
• runners.md / RUNNERS.md: Build/test commands, linters, task execution rules, and CI specs.
• GEMINI.md / CLAUDE.md: Alternative instructions files are also recognized.

You can also specify custom instruction files explicitly:

em-ollama --agents ./docs/agents.md --runners ./docs/runners.md "Review changes"

To run with all instruction files disabled:

em-ollama --no-instructions "Hello"

CLI Options

| Option | Description | | :--- | :--- | | -c, --chat | Start in Chat Mode (Default: fast conversational Q&A, no tools) | | -a, --agent | Start in Agent Mode (filesystem and command execution tools enabled) | | --mode <mode> | Select mode explicitly: chat, agent, plan, auto | | [prompt] / -p, --prompt <text> | Execute prompt directly and exit (one-shot mode) | | -m, --model <name> | Specify Ollama model (e.g. qwen2.5-coder, llama3.2) | | --host <url> | Ollama endpoint URL (default: http://127.0.0.1:11434 or $OLLAMA_HOST) | | --agents <path> | Path to custom agents.md instruction file | | --runners <path> | Path to custom runners.md instruction file | | -i, --instructions <path> | Path to additional instruction markdown file | | --no-instructions | Disable automatic discovery of agents.md / runners.md | | --list-models | List installed Ollama models and exit | | -v, --version | Show version | | -h, --help | Show CLI help |

Interactive REPL Commands

| Command | Description | | :--- | :--- | | /chat, /c | Switch to Chat Mode (conversational, no tools) | | /agent, /a | Switch to Agent Mode (tools and approvals enabled) | | /switch | Toggle between Chat and Agent modes | | /plan | Switch to Plan Mode (read-only filesystem tools) | | /models | List installed Ollama models | | /model <name> | Switch active model on the fly | | /context | Inspect active instruction files (agents.md, runners.md) and session history | | /reload | Reload agents.md and runners.md from disk | | /clear, /reset | Clear conversation history | | /pwd | Print current workspace directory | | /help | Show command reference | | /exit, /quit | Exit chat |

Programmatic API

You can also import and use em-ollama-agent directly in your JavaScript / TypeScript projects:

import { Agent, OllamaClient, loadAgentInstructions } from 'em-ollama-agent';

const client = new OllamaClient({ baseUrl: 'http://127.0.0.1:11434' }); // Or provide your url with custom port
const instructions = await loadAgentInstructions(process.cwd());

const agent = new Agent({
  client,
  root: process.cwd(),
  model: 'qwen2.5-coder',
  instructions: instructions.combined,
  mode: 'chat',
  onText: (chunk) => process.stdout.write(chunk)
});

const answer = await agent.ask('Explain how event loops work in Node.js');

Security Policy

• Safe Tools (read_file, list_directory, search_files, git_diff): Auto-approved.
• Modifications (write_file, package manager installs): Require user confirmation in Agent mode.
• Dangerous Commands (git push/reset, destructive shell commands, cloud tooling): Require explicit approval.
• Sensitive Path Guard: Blocks access to .env, private keys (.pem, .key), credentials, .aws, .ssh, and secrets.
• Workspace Confinement: Operations outside the workspace are blocked.

License

MIT © Ethern Myth