TermNet

TermNet

TermNet is an AI-powered terminal assistant that bridges a Large Language Model (LLM) with your local environment. It can safely run shell commands, search the web, and load custom tools dynamically — all while maintaining conversational memory and streaming natural language responses in real time.

Stars: 61

Visit
 screenshot

TermNet is an AI-powered terminal assistant that connects a Large Language Model (LLM) with shell command execution, browser search, and dynamically loaded tools. It streams responses in real-time, executes tools one at a time, and maintains conversational memory across steps. The project features terminal integration for safe shell command execution, dynamic tool loading without code changes, browser automation powered by Playwright, WebSocket architecture for real-time communication, a memory system to track planning and actions, streaming LLM output integration, a safety layer to block dangerous commands, dual interface options, a notification system, and scratchpad memory for persistent note-taking. The architecture includes a multi-server setup with servers for WebSocket, browser automation, notifications, and web UI. The project structure consists of core backend files, various tools like web browsing and notification management, and servers for browser automation and notifications. Installation requires Python 3.9+, Ollama, and Chromium, with setup steps provided in the README. The tool can be used via the launcher for managing components or directly by starting individual servers. Additional tools can be added by registering them in `toolregistry.json` and implementing them in Python modules. Safety notes highlight the blocking of dangerous commands, allowed risky commands with warnings, and the importance of monitoring tool execution and setting appropriate timeouts.

README:

TermNet

TermNet is an AI-powered terminal assistant that connects a Large Language Model (LLM) with shell command execution, browser search, and dynamically loaded tools.
It streams responses in real-time, executes tools one at a time, and maintains conversational memory across steps.

⚠️ Disclaimer: This project is experimental. Use at your own risk.

⚠️ Note: This has only been tested with GPT-OSS Models. Your models may behave differently.


✨ Features

  • 🖥️ Terminal integration
    Safely execute shell commands with sandboxed handling, timeout control, and built-in safety filters
  • 🔧 Dynamic tool loading
    Extend functionality by editing toolregistry.json - tools auto-discover without code changes
  • 🌐 Browser automation
    Playwright-powered web browsing, form filling, and content extraction
  • 📡 WebSocket architecture
    Real-time communication between components with streaming responses
  • 🧠 Memory system
    Tracks planning, actions, observations, and reflections across multiple steps
  • Streaming LLM output
    Integrates with Ollama for real-time chat responses
  • 🛡️ Safety layer
    Blocks dangerous commands while allowing risky ones with warnings
  • 📱 Dual interface
    Web UI and Terminal UI options
  • 🔔 Notification system
    Standalone notification server for alerts and reminders
  • 💾 Scratchpad memory
    Persistent note-taking across sessions

🌐 Architecture

TermNet uses a multi-server architecture:

  • Main WebSocket Server (main.py) - Port 876: Handles agent communication and streaming
  • Browser WebSocket Server (browser_server.py) - Port 8765: Manages Playwright browser automation
  • Notification HTTP Server (notification_server.py) - Port 5003: Handles notifications and alerts
  • Web UI Server (web_ui_server.py) - Port 5005: Browser-based interface

All servers are managed by the central launcher (run.py).

📂 Project Structure

Root Files:

  • run.py - Main launcher script
  • requirements.txt - Python dependencies
  • README.md - This file

Backend Core:

  • main.py - WebSocket server entry point
  • agent.py - TermNetAgent core logic
  • memory.py - Memory step tracking
  • safety.py - Command safety checker
  • toolloader.py - Dynamic tool loader
  • config.py - Configuration management

Tools:

  • browser_search_websocket.py - Web browsing tool
  • notification_tool.py - Notification management
  • communication_tools.py - Email/SMS capabilities
  • scratchpad.py - Note-taking tool
  • terminal.py - Terminal session wrapper

Servers:

  • browser_server.py - Browser automation server
  • notification_server.py - Notification server

⚙️ Installation

Requirements

  • Python 3.9+
  • Ollama running locally
  • Chromium (installed automatically by Playwright)

Setup

  1. Clone the repository:
git clone https://github.com/RawdodReverend/TermNet.git
cd termnet
  1. Install dependencies:
pip install -r requirements.txt
  1. Install Playwright browser:
playwright install chromium
  1. Set up Ollama (if not already installed):
curl -fsSL https://ollama.ai/install.sh | sh

🚀 Usage

Using the Launcher (Recommended)

The run.py launcher manages all components:

python run.py

You'll be prompted to choose between:

Direct Execution

For development or debugging, run components individually:

# Start the main WebSocket server
python main.py

# Start the browser server
python browser_server.py

# Start notification server
python notification_server.py

⚙️ Configuration

Key Description Default
OLLAMA_URL Base URL for Ollama server http://127.0.0.1:11434
MODEL_NAME Model name/tag to use gpt-oss:20b
LLM_TEMPERATURE Response randomness (0-1) 0.7
MAX_AI_STEPS Max reasoning steps per query 10
COMMAND_TIMEOUT Max seconds for terminal commands 30
STREAM_CHUNK_DELAY Delay between LLM output chunks 0.01

🛠️ Adding Tools

Tools are defined in toolregistry.json and implemented in Python modules.

1. Register the Tool

Add an entry to toolregistry.json:

{
  "type": "function",
  "function": {
    "name": "my_custom_tool",
    "description": "Describe what this tool does",
    "module": "mytool",
    "class": "MyTool",
    "parameters": {
      "type": "object",
      "properties": {
        "arg1": { "type": "string" }
      },
      "required": ["arg1"]
    }
  }
}

2. Implement the Tool

Create termnet/tools/mytool.py:

import asyncio

class MyTool:
    async def my_custom_tool(self, arg1: str):
        """Tool description"""
        return f"Tool executed with arg1={arg1}"
        
    # Optional: Async context management
    async def start(self):
        return True
        
    async def stop(self):
        pass

3. Restart TermNet

The tool will auto-load at startup. No code changes needed!

⚠️ Safety Notes

  • Dangerous commands (rm -rf /, shutdown, etc.) are blocked
  • Risky commands (rm, mv, chmod) are allowed with warnings
  • Always review agent suggestions before execution
  • Use in isolated environments when testing new tools
  • Monitor tool execution and set appropriate timeouts

🔌 API Reference

Core Components

  • TermNetAgent: Main agent class managing chat loop and tool execution
  • TerminalSession: Wrapper for safe command execution with timeout control
  • ToolLoader: Dynamic tool importer based on registry
  • SafetyChecker: Command safety validation system
  • BrowserSearchTool: Web browsing and content extraction
  • NotificationTool: Notification management system

📦 Dependencies

Core dependencies:

  • websockets>=12.0
  • playwright>=1.40.0
  • beautifulsoup4>=4.12.0
  • playwright-stealth>=1.0.0
  • flask>=2.3.0
  • aiohttp>=3.9.0
  • lxml>=4.9.0
  • html5lib>=1.1
  • soupsieve>=2.5

🐛 Troubleshooting

  • Browser won't start: Run playwright install chromium and check if Chrome is installed
  • Ollama connection refused: Ensure Ollama is running: ollama serve
  • Port already in use: Change ports in respective server files or kill existing processes
  • Tool not loading: Check toolregistry.json syntax and Python module paths
  • Web UI not accessible: Check firewall settings and ensure port 5005 is open

📜 License

This project is licensed under the MIT License.

See LICENSE file for details.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for TermNet

Similar Open Source Tools

For similar tasks

For similar jobs