Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (darkfoo-code) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Darkfoo Code

A local AI coding assistant CLI powered by Ollama. Built with TypeScript, React + Ink, and native Ollama tool calling.

Features

Interactive REPL with streaming responses and Darkfoo-branded terminal UI
Non-interactive mode (-p) for scripting
14 tools: Bash, Read, Write, Edit, Grep, Glob, WebFetch, Plan mode, Tasks, and more
Slash commands: /model, /clear, /compact, /cost, /context, /diff, /commit, /history
! bash mode for direct shell execution
Arrow-key command history and slash command tab-completion
Generator-based conversation loop with multi-turn tool use
Plan mode for structured implementation planning
Task tracking system (create, update, list tasks)
Session persistence with auto-save and resume
DARKFOO.md project context system (like CLAUDE.md)
Permission system with settings storage
Markdown rendering in terminal output
Context window usage tracking and compaction

Requirements

Node.js 22+
Ollama running locally
A model with tool calling support (e.g. llama3.1:8b)
ripgrep (rg) installed for Grep/Glob tools

Setup

npm install
ollama pull llama3.1:8b    # or any tool-calling model
sudo dnf install ripgrep   # Fedora — or your distro's equivalent

Usage

# Interactive REPL
npm run dev

# Single prompt
npm run dev -- -p "Read /etc/hostname"

# Global command (after npm link)
npm link
darkfoo
darkfoo -p "What files are in src/?"
darkfoo -m llama3.1:8b

Slash Commands

Command	Description
`/help`	List available commands
`/model [name]`	List or switch Ollama models
`/clear`	Clear conversation history
`/compact`	Compress conversation to save context
`/cost`	Show token usage for session
`/context`	Show context window usage with visual bar
`/diff`	Show uncommitted git changes
`/commit [msg]`	Stage and commit with AI-generated message
`/history`	List saved sessions
`/resume <id>`	Resume a saved session
`/exit`	Exit Darkfoo Code

Prefix with ! to run shell commands directly (e.g. !ls -la, !git status).

Tools

Tool	Description
Bash	Execute shell commands with timeout and output limits
Read	Read files with line numbers, offset/limit support
Write	Write files, creating parent directories as needed
Edit	Find-and-replace with quote normalization and diff output
Grep	Search file contents via ripgrep (regex, glob filtering)
Glob	Find files by pattern via ripgrep
WebFetch	Fetch URLs and return text content
EnterPlanMode	Enter structured planning mode (read-only exploration)
ExitPlanMode	Submit plan for user approval
TaskCreate	Create a tracked task
TaskUpdate	Update task status (pending/in_progress/completed)
TaskList	List all tasks
TaskGet	Get task details
AskUserQuestion	Prompt user for clarification

Project Context (DARKFOO.md)

Place a DARKFOO.md file in your project root or ~/.darkfoo/DARKFOO.md for global instructions. Rules can also go in .darkfoo/rules/*.md. These are automatically loaded into the system prompt.

Session Persistence

Sessions auto-save to ~/.darkfoo/sessions/. Use /history to browse and /resume <id> to continue a previous session.

Project Structure

src/
  main.tsx              CLI entry (Commander.js)
  app.tsx               Ink app wrapper + context
  repl.tsx              Interactive REPL screen
  query.ts              Generator-based conversation loop
  ollama.ts             Ollama /api/chat streaming client
  types.ts              Core message and event types
  system-prompt.ts      System prompt builder + DARKFOO.md loader
  state.ts              App state (plan mode, tasks)
  session.ts            Session save/load/list
  context-loader.ts     DARKFOO.md discovery and loading
  permissions.ts        Permission system + settings
  commands/             Slash command implementations
  tools/                Tool implementations (14 tools)
  components/           React + Ink UI components
  utils/                Theme, formatting, markdown renderer

Ollama Model Compatibility

Models must support Ollama's native tool calling. Tested and working:

llama3.1:8b — recommended default, solid tool calling
llama3.2:3b — works but limited reasoning at 3B

Models that do not support tool calling: gemma2, phi4, deepseek-r1, gpt-oss.

Environment Variables

Variable	Description	Default
`OLLAMA_HOST`	Ollama API base URL	`http://localhost:11434`