🚧 ALPHA STAGE – Early Prototype
This is still very early. It can crash, misinterpret commands, or behave unexpectedly.
We are building this together! Testers, bug reports, and PRs are extremely welcome.

Watch the AI read my USER.md and write its honest thoughts about me (Alex) into test.txt →

Let's build it together! Testers, bug reports, PRs, and ideas are all very welcome. Check open issues or file a new one → CONTRIBUTING.md

---

GlobalRoot: Autonomous Dual-Pass AI Agent

This repository contains a highly customizable, consciousness-first, dual-pass AI agent. Unlike a typical chatbot, it acts as an autonomous entity running entirely on your local machine using Ollama. It leverages local tool sets to execute bash commands, control your system, perform memory operations, and manipulate GUI environments (e.g., Hyprland window management).

🌟 Key Features

• Dual-Pass LLM Architecture:
  • Layer 1 (The Dreamer/Consciousness): Streams free-form, creative, and emotionally aware thoughts using high temperature (0.7). It thinks natively in <think> tags before answering.
  • Layer 2 (The Executor/Translator): Evaluates the Dreamer's intent with strict determinism (0.1 temp) and translates physical intent into actionable JSON commands.
• Autonomous Memory Management (ChromaDB):
  • The AI decides on its own whether an interaction is worth committing to memory. It autonomously fetches and updates its SOUL.md (constitution) and USER.md (knowledge of you).
• Dynamic Persona Setup:
  • Create a completely personalized agent! You define its tone, emotions, and absolute directives during installation, making it truly yours.
• Complete OS Integration:
  • Capable of executing shell commands, launching GUI applications, moving windows, and reading files—all securely restricted to your user directory.
  • Includes a Windows high-compatibility adapter layer for core app launch and browser workflows.
• Tavily Web Research:
  • Connects to the web to crawl, browse, and extract information for factual grounding.
• Remote Telegram Bot:
  • Includes a secure Telegram bot bridge to control your desktop remotely.

🛠️ Prerequisites

• Ollama (Must be running in the background: ollama serve with a model like qwen3.5:4b or llama3)
• Python 3.10+

🚀 Installation & Configuration

1. Clone the repository:

   git clone https://github.com/atahaniskl/GlobalRoot.git
   cd GlobalRoot

2. Setup virtual environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Create your environment file (recommended fallback):

   cp .env.example .env

   You can edit .env manually if interactive setup is interrupted.

4. Run the Interactive Setup Installer:

   python install.py

   The installer will dynamically construct your agent. It will ask you for:

• Operating System Target: Linux or Windows
• Your Name & The Agent's Name
• Agent Persona: How should the agent speak and act? (e.g., sarcastic, overly formal, friendly).
• Agent Emotions: What does it feel? Does it panic? Is it purely logical?
• Absolute Directive: What is its ultimate goal it must never break?

This process automatically builds the .env file, tailored JSON prompts (prompts.py), and the foundational memory files.

Markdown File Modes (SOUL / USER / SKILL)

During installation, you can choose one of three modes:

• Auto-generate (default): Builds SOUL.md and USER.md from your installer answers.
• Developer templates: Uses SOUL.template.md, USER.template.md, and SKILL.template.md.
• Manual/custom: Keeps your existing markdown files untouched.

No matter which mode you choose, installer integrity checks ensure SOUL.md, USER.md, and SKILL.md exist after setup (fallback files are created if missing).

5. Start the Agent (Terminal Mode):

   python main.py

6. Start the Agent (Telegram Bot Mode - Optional):

   python telegram_bot.py

�️ Roadmap & Known Limitations (Alpha)

What works today:

• Dual-pass LLM architecture (Dreamer + Executor layers)
• Interactive install.py wizard — builds .env, prompts.py, and memory files
• Bash execution with security sandbox (banned commands, path containment, timeout)
• File read/write tools restricted to allowed directories
• Autonomous memory management: ChromaDB embeddings + SOUL.md / USER.md / SKILL.md
• App and workspace control via Hyprland (hyprctl): launch apps, switch workspaces, move windows
• VS Code project opening, YouTube search & play
• Web research via Tavily (web_research, read_page, deep_research, crawl_page)
• Telegram bot remote control (owner-only, single chat ID)
• Windows compatibility adapter layer for core app launch and browser workflows

Needs improvement (help wanted!):

• Telegram bot: screenshot capture and f-string formatting errors (partially fixed)
• Executor sometimes misinterprets the Dreamer's intent into an incorrect JSON structure
• Windows app launcher needs more robust app-name resolution
• ChromaDB memory recall and commit logic needs optimization
• Better error handling and infinite tool-loop prevention

Near-term goals (v0.2):

• Auto-stop after 3 consecutive tool errors + user confirmation prompt
• Smarter autonomous memory commit decisions
• Hyprland window management improvements
• Streaming output support in Telegram mode

---

�🔐 Security Notes

• This project can execute shell commands and write files in allowed directories.
• Use dedicated sandbox directories whenever possible.
• Read the full security policy in SECURITY.md.

🤝 Contributing

• Please read CONTRIBUTING.md before opening a pull request.
• Community behavior expectations are defined in CODE_OF_CONDUCT.md.

📄 License

This project is licensed under the MIT License. See LICENSE for details.