🤖 DesktopAgent

A secure, platform-native agentic daemon that translates natural language intent into local operating system commands.

DesktopAgent utilizes a split-process architecture consisting of a cognitive engine (Brain) and a platform-native executor (Hands), communicating over a local IPC channel. This architecture separates high-level ReAct reasoning from safe, low-level system call execution.

---

🏗️ Architecture

graph TD
    User([🗣️ User Input]) --> Brain[🧠 Brain Daemon - TypeScript/Node]
    
    subgraph Brain [🧠 Brain Process]
        direction TB
        Agent[ReAct Agent Loop] --> LLM[🦙 Ollama: llama3]
        Agent --> Embed[🔤 Ollama: nomic-embed-text]
        Agent --> VDB[(💾 SQLite-Vec Memory DB)]
    end
    
    Brain -- "🔗 IPC Socket (Linux) / Named Pipe (Windows)" --> Hands[💪 Hands Daemon - C++]
    
    subgraph Hands [💪 Hands Process]
        direction TB
        Parser[Request Parser] --> Tools[🛠️ System Tools]
        Tools --> OS["💻 Target OS (Linux/Windows)"]
    end

Loading

The system is separated into two decoupled components:

1. The Brain (brain/ - TypeScript/Node)

   • Cognitive Routing: Hosts the main ReAct (Reasoning and Acting) loop using Llama 3.
   • Local Embeddings: Integrates with nomic-embed-text to generate vector representations of task history.
   • Vector Database: Leverages SQLite's sqlite-vec extension in-memory to store and query episodic memory.
   • Security Approval: Promptly intercepts raw bash execution requests and prompts the user for manual confirmation.

2. The Hands (agent_hands/ - C++17)

   • Daemon Service: Runs as a lightweight, low-level service listening on a Unix Domain Socket (/tmp/hands.sock on Linux) or a Named Pipe (\\\\.\\pipe\\hands_pipe on Windows).
   • Tool Execution: Executes precise system-level commands (e.g., file system management, calendar/alarm scheduling, log fetching) parsed via JSON payloads.

---

📋 Prerequisites

Before setting up the project, make sure you have the following installed on your system:

1. Ollama (Local LLM Daemon)

Install Ollama from ollama.com and verify it's running.

You must pull the two models used by this project:

# Pull the main cognitive LLM
ollama pull llama3

# Pull the vector embedding model
ollama pull nomic-embed-text

2. Node.js & npm

• Node.js (v18+ recommended)
• npm (v9+)

3. C++ Build Tools

• CMake (v3.10+)
• A compiler supporting C++17 (e.g., GCC, Clang, or MSVC)

---

⚡ Quick Start (Linux)

For Linux systems, a comprehensive boot script boot_agent.sh is provided in the root directory. This script automates the entire process:

• Configures and builds the C++ daemon (agent_hands).
• Verifies and installs Node dependencies in brain (if node_modules is missing).
• Compiles the TypeScript brain code.
• Checks if the Ollama service is running, attempts to start it if not, and verifies both llama3 and nomic-embed-text models are pulled.
• Launches both processes and binds them together, presenting the agent's interactive terminal.

To use the automated script:

1. Make the script executable (run once):

   chmod +x boot_agent.sh

2. Run the boot script:

   ./boot_agent.sh

Tip

Press Ctrl+C to terminate the agent session. The script traps this interrupt signal and gracefully closes all background services (like the C++ daemon and background Ollama server if started by the script) to clean up system resources.

---

🚀 Manual Setup & Installation

Step 1: Build the C++ Execution Daemon (agent_hands)

From the repository root, compile the platform execution daemon:

# Create a build directory and configure the project
cmake -S agent_hands -B build

# Build the executable
cmake --build build

This produces the executable binary named hands inside the build/ directory.

Step 2: Set Up the Node.js Cognitive Engine (brain)

Navigate to the brain/ directory, install package dependencies, and compile TypeScript:

# Navigate to brain folder
cd brain

# Install SQLite dependencies and types
npm install

# Compile TypeScript code to JS (outputs to brain_dist/)
npx tsc

---

🏃 Running the Project

To run the desktop agent, you need both the executor daemon and the cognitive agent running.

1. Start the C++ Daemon

Start the C++ execution service first so that the socket/named pipe is initialized:

# From the project root:
./build/hands

Outputs: Starting Agentic Hands Daemon... (Listening on /tmp/hands.sock or Windows Pipe).

2. Start the Cognitive Brain

In a new terminal window, start the TypeScript agent:

# From the project root:
node brain_dist/index.js

Outputs: Initializing Agentic Brain... followed by Brain Online. Awaiting OS commands....

---

🛠️ Interface & Commands

Once started, type any natural language prompt into the Brain CLI:

• Example: Create a directory named projects and put a file named hello.txt in it containing the text 'hello world'
• Example: Set an alarm for 08:30
• Security Check: If the model tries to run raw terminal commands, it will output a red [ SECURITY CHECK ] warning and request your manual permission ([Y/N]) before executing.

Type exit or quit to shutdown the agent gracefully.