agntk

AI agent you install and point at problems. Zero config. Works immediately.

npx agntk "fix the failing tests"

No API keys required — a free tier is included. Bring your own key or install Ollama for unlimited local use.

---

Quick Start

# One-shot: give it a task
npx agntk "organize this folder by file type"

# Named agent: remembers context across sessions
npx agntk -n coder "refactor the auth module to use JWT"

# Interactive REPL
npx agntk -n coder -i

# Pipe input
cat error.log | npx agntk "explain these errors and suggest fixes"

# List your agents
npx agntk list

# Inspect or manage an agent
npx agntk info coder
npx agntk clean

That's it. No config files. No API key setup (unless you want to). It reads your files, runs commands, browses the web, spawns sub-agents, and remembers what it learns.

After any one-shot prompt, you can type follow-up messages directly — the agent stays in the terminal and remembers the conversation. Use -q to disable this and exit immediately.

---

What It Does

Out of the box, every agent has 20+ built-in tools:

• Files — read, write, edit, create, glob, grep across your workspace
• Code — AST-aware search and replace via ast-grep
• Shell — run commands, manage background processes
• Browser — navigate, extract, interact with web pages
• Planning — break down complex tasks, deep reasoning for hard problems
• Memory — remember facts, recall context, build knowledge across sessions
• Sub-agents — spawn specialized agents for parallel work, with live activity streaming
• Skills — auto-discover SKILL.md files for project-specific capabilities
• Governance — three-tier behavioral framework (CORE identity > human rules > agent instincts)
• Growth loop — agents log events, synthesize daily journals, and create learned instincts

---

Zero-Config Provider Cascade

agntk auto-detects the best available AI provider:

Priority	Provider	How it's detected
1	Your API key	OPENROUTER_API_KEY, OPENAI_API_KEY, or CEREBRAS_API_KEY in env
2	Ollama	Auto-detected at localhost:11434 — picks the right model for your hardware
3	Free tier	Built-in, no setup — backed by Cerebras (rate-limited)

# Use your own key for unlimited access (recommended)
export OPENROUTER_API_KEY=sk-or-...

# Or use local models — just install Ollama, agntk finds it automatically
# https://ollama.com

# Or just run it — the free tier works out of the box
npx agntk "hello"

---

CLI Reference

agntk "prompt"                    Run a one-shot task
agntk -n <name> "prompt"          Named agent (persistent memory)
agntk -n <name> -i                Interactive REPL
agntk list                        List all agents
agntk info <name>                 Show agent details
agntk delete <name>               Delete an agent's state
agntk stop <name>                 Stop a running agent
agntk clean                       Interactively remove stale agents
agntk completions <shell>         Output shell completion script
agntk install <file.md>           Install a capability into the agent's harness
agntk uninstall <path>            Remove an installed capability
agntk evaluate <file.md>          Validate a capability file

Options

Flag	Short	Description
--name	-n	Agent name (enables persistent memory)
--instructions		Custom system prompt
--interactive	-i	Interactive REPL mode
--workspace		Workspace root (default: current directory)
--max-steps		Max tool-loop steps (default: 25)
--verbose		Show full tool args and output
--quiet	-q	Text output only (no follow-up, for piping)
--version	-v	Show version
--help	-h	Show help

Agent Management

Command	Description
list	Show all agents with status (running/idle) and last active time
info <name>	Agent details — memory files, workspace, sub-agents, token usage, disk size
delete <name>	Delete an agent's state directory (with confirmation)
stop <name>	Send SIGTERM to a running agent; SIGKILL if it doesn't exit
clean	Interactive picker to bulk-delete idle agents
completions	Output shell completion script (bash, zsh, fish)
install	Validate and install a capability (rule, instinct, skill) into the harness
uninstall	Remove an installed capability file
evaluate	Validate a capability file without installing it

Interactive REPL

In REPL mode (-i or follow-up after one-shot), press TAB after / for autocomplete:

Command	Description
/help	Show available commands
/tools	List available tools
/agents	List all agents
/model	Show current model info
/memory	Show agent memory files
/status	Show session stats
/verbose	Toggle verbose output
/clear	Clear conversation history
/exit	Quit the REPL

Shell Completion

Tab completion for commands, flags, and agent names in your shell:

# Install globally for shell completion
npm i -g agntk

# Completions auto-install on first run (bash/zsh/fish)
# Or generate manually:
agntk completions zsh

When installed globally, agntk auto-detects your shell, writes the completion script to ~/.agntk/completions/, and patches your rc file. No manual setup needed.

Examples

# Fix bugs
npx agntk -n coder "the login page crashes when the session expires — find and fix it"

# DevOps
npx agntk -n ops --instructions "you manage k8s deploys" "roll back staging"

# Research
npx agntk "compare React Server Components vs Astro islands — pros, cons, benchmarks"

# Code review
npx agntk "review src/ for security issues and suggest fixes"

# Pipe anything
git diff | npx agntk "write a commit message for this diff"
cat package.json | npx agntk "are any of these dependencies outdated?"

# Agent management
npx agntk info coder
npx agntk delete old-agent
npx agntk clean

---

Named Agents & Memory

Give an agent a name and it remembers context across sessions:

# First session — agent learns about your project
npx agntk -n myproject "read the codebase and understand the architecture"

# Later session — agent already knows the context
npx agntk -n myproject "add rate limiting to the API endpoints"

# See what agents exist
npx agntk list

Memory is stored at ~/.agntk/agents/{name}/ as plain markdown files:

Path	Description
memory/memory.md	Agent-curated facts about your project
memory/decisions.md	Append-only log of decisions made
memory/preferences.md	Cross-project preferences
memory/identity.md	Human-authored identity (you can edit this)
memory/project.md	Human-authored project context
context.md	Session context the agent rewrites as it learns

---

Hardware-Aware Local Inference

When Ollama is detected, agntk checks your hardware and picks the largest model your system can run comfortably:

Your RAM	Model Selected	Why
8 GB	qwen3:8b for everything	Fits in memory with room for OS
16 GB	qwen3:14b standard, qwen3:8b fast	Best balance of quality and speed
32+ GB	qwen3:32b reasoning, qwen3:14b standard	Full power for complex tasks

Apple Silicon unified memory, NVIDIA VRAM, and CPU-only systems are all detected automatically. The agent tells you what it picked:

  provider: ollama (http://localhost:11434)
  models:   32 GB RAM → qwen3:32b for reasoning/powerful, qwen3:14b for standard

---

Harness Governance

Agents can operate under a three-tier governance system that defines behavioral boundaries:

Tier	Directory	Author	Purpose
CORE	core.md	Human	Frozen identity — purpose, values, ethics
Rules	rules/	Human	Behavioral boundaries the agent must follow
Instincts	instincts/	Agent	Learned behaviors from experience (draft by default)

Enable governance on any agent:

const agent = createAgent({
  name: 'governed-agent',
  harness: { root: './harness' },
});

The agent automatically gets a create_instinct tool to persist learned behaviors. Events are logged for daily journal synthesis, closing the growth loop.

# Install a capability file
agntk -n myagent install rules/safety.md

# Validate before installing
agntk evaluate my-instinct.md

---

For Developers

The CLI is built on @agntk/core, which you can use directly in your own projects:

import { createAgent } from '@agntk/core';

const agent = createAgent({
  name: 'my-agent',
  instructions: 'You are a helpful coding assistant.',
  workspaceRoot: process.cwd(),
});

const result = await agent.stream({ prompt: 'Read package.json and list the dependencies' });

for await (const chunk of result.fullStream) {
  if (chunk.type === 'text-delta') process.stdout.write(chunk.text ?? '');
}

Packages

Package	Description
agntk	CLI — npx agntk entry point
@agntk/core	Agent factory — tools, streaming, memory, sub-agents, hooks
@agntk/cli	CLI implementation
@agntk/server	HTTP server — REST + SSE + WebSocket endpoints
@agntk/client	Client library — HTTP, SSE, WebSocket
@agntk/search	Web search with provider fallback (DuckDuckGo, Brave, etc)
@agntk/logger	Structured logging with namespace filtering

Custom Tools

const agent = createAgent({
  name: 'my-agent',
  tools: {
    myCustomTool: {
      description: 'Does something custom',
      parameters: z.object({ input: z.string() }),
      execute: async ({ input }) => ({ output: `Processed: ${input}` }),
    },
  },
});

Custom tools are merged with the 20+ built-in tools.

Model Tiers

Every provider has 4 model tiers. Override via environment variables:

Tier	Purpose	Env Override
fast	Quick responses, low cost	AGENT_SDK_MODEL_FAST
standard	Balanced quality/cost	AGENT_SDK_MODEL_STANDARD
reasoning	Complex logic, planning	AGENT_SDK_MODEL_REASONING
powerful	Best quality, highest cost	AGENT_SDK_MODEL_POWERFUL

Server & Client

Expose any agent as an HTTP API:

import { createAgentServer } from '@agntk/server';
import { createAgent } from '@agntk/core';

const agent = createAgent({ name: 'api-agent', instructions: 'You help with API tasks.' });
const server = createAgentServer({ agent, port: 3000 });
server.start();
// POST /stream, POST /chat, GET /health, WS /ws/browser-stream

Connect from anywhere:

import { AgentHttpClient } from '@agntk/client';

const client = new AgentHttpClient('http://localhost:3000');
for await (const event of client.generateStream({
  messages: [{ role: 'user', content: 'Hello' }],
})) {
  if (event.type === 'text-delta') process.stdout.write(event.textDelta);
}

Advanced Features

Available via sub-path imports:

import { ... } from '@agntk/core';          // Core essentials
import { ... } from '@agntk/core/evals';     // Eval suite and assertions
import { ... } from '@agntk/core/advanced';  // Durability, hooks, guardrails, reflection, observability

Features include: durable workflows (crash recovery), workflow hooks (human-in-the-loop approval), guardrails (PII filtering), reflection (always-on self-critique), observability (Langfuse + OpenTelemetry), and best-of-N evaluation.

---

Requirements

• Node.js >= 20
• For local models: Ollama (optional, auto-detected)

License

MIT