🐈 Katto

A powerful conversational AI coding agent for the terminal, powered by DeepSeek.

Katto is a Node.js CLI agent that interacts with your file system, the web, PostgreSQL databases, and git — driven by natural language. It features persistent memory, multi-turn conversations, real-time streaming responses, and a full tool harness, all from your terminal.

$ katto 'create a folder named test'
$ katto 'read and follow file prompt.txt'
$ katto 'change all functions to lowercase in main.js'
$ katto 'create a todo list app in node js using the browser local storage, no other dependencies than express and ejs, dark/light theme and responsive'

✨ Features

Persistent memory

• Session-based conversations — Katto remembers context across invocations.
• File system memory — automatically tracks every file it touches (size, type, modification time).
• User notes — store and recall important info across sessions (remember_note / recall_notes).
• Disk persistence — everything survives terminal restarts (stored in ~/.katto/).
• Tool history — every action is logged with timestamps and session id.

Multi-turn conversations

• Maintains context across multiple exchanges.
• References previous interactions naturally.
• Handles follow-ups and clarifications:
  • "Remember my config file path" → "What was that config path again?"

Real-time streaming

• Watch Katto think (reasoning tokens) and act step-by-step.
• Live tool calls, progress steps, tool usage counts, and elapsed time.

📦 Installation

Requires Node.js 18+ and an npm package manager.

# clone / copy the project, then:
npm install
npm link        # makes the `katto` command available globally
# or: npm install -g .

Configuration

IMPORTANT: For global access create a ~/.env.katto file with env vars

# Required
export AGENT_API_KEY=sk-your-key-here

# Optional
export AGENT_MODEL=deepseek-v4-flash   # or deepseek-v4-pro deepseek-reasoner
export MEMORY_HOME=~/.katto            # memory location (default ~/.katto)

See .env.example for the full list (including PostgreSQL settings).

🚀 Usage

One-shot

$ katto 'create a folder named test'
$ katto 'list files and summarize the project'
$ katto --session work 'what did we do last time?'
$ katto --new 'start fresh: scaffold a node project'
$ katto --model deepseek-reasoner 'explain this git history'

Interactive mode

$ katto
🐈 Katto — AI coding agent · deepseek-chat · type /help for commands
katto> create a folder named test
katto> remember my config file path is ./config.json
katto> what was that config path again?

| Command | Description | | --- | --- | | /help | Show help | | /exit, /quit | Exit Katto | | /new | Start a new session | | /session <id> | Switch sessions | | /sessions | List sessions | | /model <name> | Switch model | | /notes | Show stored notes | | /remember <k> <v> | Store a note | | /forget-note <key> | Delete a note | | /history | Show recent tool history |

Utility commands

$ katto --sessions              # list saved sessions
$ katto --notes                 # show stored notes
$ katto --forget-note my-key    # delete a note
$ katto --version
$ katto --help

🧰 Tool catalogue

Katto exposes 50+ tools to the model.

File system

| Tool | Purpose | | --- | --- | | read_file | View any text file | | write_file | Create/overwrite files | | create_folder | Build folder structures | | delete | Remove files / empty dirs | | move_rename | Move or rename files/folders | | list_directory | Explore folder contents | | file_info | Size, dates, permissions | | search_files | Find files by glob/name | | search_content | Grep file contents |

Web

| Tool | Purpose | | --- | --- | | fetch_url | Fetch any URL | | fetch_and_parse_json | Fetch + parse JSON APIs | | download_file | Download and save files |

PostgreSQL

| Tool | Purpose | | --- | --- | | pg_query | Any SQL with parameters | | pg_list_tables | Tables with metadata | | pg_describe_table | Detailed table schema | | pg_get_schema | Full database schema | | pg_generate_data | Random test data | | pg_table_stats | Table statistics | | pg_create_table | Create tables | | pg_alter_table | Alter tables | | pg_drop_table | Drop tables (caution) | | pg_list_indexes | Indexes | | pg_list_foreign_keys | Relationships | | pg_list_sequences | Sequences | | pg_transaction | Atomic multi-query transactions |

Git

git_init, git_status, git_add, git_commit, git_branches, git_create_branch, git_checkout, git_delete_branch, git_log, git_diff, git_reset_hard, git_reset_soft, git_revert, git_stash, git_stash_pop, git_merge, git_file_history, git_uncommitted_files, git_create_tag, git_tags

Memory

remember_note, recall_notes, forget_note, plus automatic file tracking.

🛠️ How it works

┌─────────────────────────────────────────────────────────────┐
│  terminal:  katto "create a folder named test"             │
└──────────────────────────┬──────────────────────────────────┘
                           ▼
              ┌───────────────────────┐
              │   Agent loop          │
              │  • load session       │
              │  • stream DeepSeek    │──► reasoning + text + tool calls
              │  • execute tools      │
              │  • persist memory     │
              └───────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
   File system        Web / APIs         PostgreSQL / git
   (sandboxed)        (fetch tools)      (pg_* / git_* tools)

• Agent loop (src/agent/agent.js) streams from the DeepSeek OpenAI-compatible API, executes requested tools, feeds results back, and repeats until the model gives a final answer.
• Tool registry (src/tools/registry.js) is the single catalogue of all tools; each returns a string the model can read (errors included).
• Path safety (src/utils/paths.js) sandboxes all file operations to the working directory, blocking directory-traversal.
• Memory store (src/memory/store.js) persists sessions, notes, file metadata, and tool history as JSON with atomic writes.

📁 Project layout

katto/
├── bin/katto.js            # CLI entry point
├── src/
│   ├── cli.js              # arg parsing, one-shot + interactive REPL
│   ├── config.js           # env + persisted config
│   ├── index.js            # programmatic API
│   ├── agent/
│   │   ├── agent.js        # core agent loop (streaming + tool calls)
│   │   └── system-prompt.js
│   ├── llm/
│   │   └── deepseek.js     # DeepSeek streaming client
│   ├── memory/
│   │   └── store.js        # disk-persistent memory
│   ├── tools/
│   │   ├── registry.js
│   │   ├── filesystem.js
│   │   ├── web.js
│   │   ├── database.js
│   │   ├── git.js
│   │   └── memory.js
│   └── utils/
│       ├── formatting.js
│       └── paths.js        # path-safety sandbox
├── package.json
├── .env.example
└── README.md

⚠️ Safety notes

• Path sandboxing: file tools refuse to touch anything outside the working directory.
• Destructive git (git_reset_hard, git_delete_branch -D, recursive deletes, pg_drop_table) are available but Katto is instructed to use them only when explicitly requested.
• Your AGENT_API_KEY is only read from env; it is never written to disk.

License

GPL