scratchpad-cli

Scratchpad CLI

A lightweight, terminal-first AI assistant client written in Go.

Scratchpad CLI provides a clean command-line interface for interacting with a locally hosted AI backend. It abstracts backend lifecycle management, session persistence, document ingestion, and streaming AI interactions behind a simple developer-friendly interface.

The project is designed around a thin-client architecture where the CLI is responsible for user interaction and backend orchestration, while all AI-specific functionality remains encapsulated within the Python backend.

GitHub Repository

Features

🚀 Terminal-first AI assistant
💬 Persistent conversation threads
📄 Knowledge ingestion for PDF and TXT documents
⚡ Streaming assistant responses
🔄 Automatic backend installation and setup
🐍 Automatic Python virtual environment creation
🔧 Backend lifecycle management
🖥 Interactive command shell
🧩 Modular and extensible architecture
📝 Lightweight Go implementation

Architecture

                               +-----------------------+
                               |    Scratchpad CLI     |
                               |      Go + Cobra       |
                               +-----------+-----------+
                                           |
                                   HTTP REST Interface
                                           |
                               +-----------v-----------+
                               |    Python Backend     |
                               |   AI Agent Platform   |
                               +-----------+-----------+
                                           |
             +-----------------------------+-----------------------------+
             |                             |                             |
     Conversation Memory             Knowledge Base                 AI Agents
          (Threads)                      (RAG)                     & Tool Calling

The CLI intentionally contains no AI logic.

Its responsibilities are limited to:

User interaction
Command parsing
Session persistence
Backend startup and shutdown
HTTP communication
Streaming server responses

The backend is responsible for:

Agent execution
LLM orchestration
Tool calling
Knowledge retrieval
Conversation memory
AI workflows

This separation allows both components to evolve independently while keeping the CLI lightweight.

Repository Structure

cmd/
└── scratchpad/
    └── Application entry point

internals/

├── apiRequests/
│   HTTP client layer
│
├── backend/
│   Backend lifecycle management
│
├── cli/
│   Cobra commands and interactive shell
│
└── envSetup/
    Environment bootstrap
        ├── Python verification
        ├── Backend download
        ├── Virtual environment creation
        └── Dependency installation

README.md
LICENSE
go.mod

Installation

Requirements

Go 1.25+
Python 3.12.12 or later
Git

Clone

git clone https://github.com/tuhindutta/scratchpad-cli.git

cd scratchpad-cli

Build

go build -o scratchpad

go install

First Run

Start the backend.

scratchpad start

On first execution Scratchpad automatically performs the following:

Verify Python installation
        │
        ▼
Download backend repository
        │
        ▼
Create Python virtual environment
        │
        ▼
Install backend dependencies
        │
        ▼
Launch backend server
        │
        ▼
Ready for requests

No manual backend installation is required.

Interactive Shell

Launch the built-in shell.

scratchpad shell

Example session

scratchpad>

start

chat Explain Retrieval Augmented Generation.

thread list

knowledge

exit

Available Commands

Command	Description
`start`	Download (first run) and start backend
`stop`	Shutdown backend
`chat`	Send prompt to assistant
`knowledge`	Import PDF/TXT documents
`thread list`	List conversation threads
`thread delete`	Delete a conversation thread
`thread clear`	Delete all conversations
`credentials get`	Show current credentials
`credentials set`	Set user/thread IDs
`shell`	Launch interactive shell
`version`	Show application version

Session Management

Scratchpad stores the following metadata locally:

User ID
Thread ID
Backend Port

This enables persistent conversations across CLI sessions.

If credentials are unavailable, Scratchpad automatically creates a temporary session.

Streaming Responses

Assistant responses are streamed incrementally as execution progresses.

Example

===== ASSISTANT =====

[Planner]

Node: Planner

Type: assistant

Content:
Planning task...

[Retriever]

Node: Retriever

Type: tool

Tool Name: search_documents

Content:
Searching knowledge base...

[Assistant]

Node: Assistant

Type: assistant

Content:
Final response...

Streaming provides visibility into intermediate execution instead of waiting for the entire workflow to complete.

Knowledge Ingestion

Scratchpad supports importing external documents into the backend knowledge base.

Supported formats

Once ingested, documents become available to the backend retrieval pipeline for future conversations.

Design Philosophy

Scratchpad was built around a few core principles.

Terminal-first workflow
Minimal setup
Lightweight client
Persistent AI sessions
Streaming interactions
Clean separation of responsibilities
Extensible architecture
Simple developer experience

Why Go?

Go was chosen for the CLI because it provides:

Small self-contained binaries
Excellent concurrency primitives
Fast startup time
Strong standard library
Easy cross-platform compilation

Why Python?

Python powers the backend because of its rich AI ecosystem.

It provides seamless integration with:

LLM frameworks
Agent orchestration
Retrieval pipelines
Machine learning libraries
Tool integrations

Keeping AI functionality inside the backend allows the CLI to remain lightweight and language-agnostic.

Why HTTP?

Communication between the CLI and backend uses HTTP.

Advantages include:

Simplicity
Easy debugging
Backend language independence
Streaming support
Future compatibility with remote deployments

Future Work

Planned improvements include

Multiple model providers
MCP integration
Plugin architecture
Configuration management
Cross-platform release binaries
Docker deployment
Enhanced logging
Authentication improvements
Shell autocompletion

License

This project is licensed under the MIT License.

See the LICENSE file for details.

Author

Tuhin Kumar Dutta

Portfolio Website: https://www.tuhindutta.com/

This site is open source. Improve this page.