🗂️ Table of Contents

• What is CausalLoop?
• How It Works
• Agent Features
• Live Tools Suite
• Interactive Previews
• Installation Guide
• Architecture Flow
• Agent Identity Profile
• Project Settings
• File Layout
• Technology Stack

💡 What is CausalLoop?

Have you ever had a bug that just kept coming back? Or wondered why your team keeps making the exact same mistakes?

CausalLoop is an AI assistant that lives directly in your terminal. It doesn’t just find bugs—it figures out why they happened in the first place. Think of it as a strict system inspector for your software. When a mistake happens, most tools blame the developer. CausalLoop looks at your whole system—your rules, your tests, and your checks—to find out which safety net failed.

"Instead of saying 'Bob wrote a bad line of code,' CausalLoop tells you: 'Your testing process is broken, your team skips reviews, and you have no automated checks to catch this error before it goes live.'"

It works across three timeframes:

• Yesterday: It looks at your old code to find hidden problems and old passwords.
• Today: It looks at current, live bugs and asks "Why?" over and over until it uncovers the real issue.
• Tomorrow: It reviews new changes before they are merged, warning you if you are about to make an old mistake again.

🌟 Agent Features

Here is what the CausalLoop agent can do automatically for your project. All investigations stream their analysis instantly into your CLI, but also generate a rigorous .md markdown report saved directly to your filesystem, allowing your team to safely persist and reference the exact findings later.

| Module | What it does | Goal | Output | |---|---|---|---| | repo-autopsy 🩸 | Deep scans your code for bad habits | Find hidden problems | autopsy-report.md | | secret-scanner 🗝️ | Searches for accidentally saved passwords | Keep data safe | Terminal / Logs | | dependency-audit 🥫 | Checks your third-party packages | Stop supply-chain risks | Terminal / Logs | | compliance-check 📝 | Makes sure required standard files exist | Keep projects tidy | Terminal / Logs | | mortem-interrogator 🚨 | Reads real bugs and finds the true cause | Stop the blame game | systemic-finding.md | | merge-risk 🛑 | Checks new code against old failures | Stop repeat mistakes | merge-risk.md |

🧰 Live Tools Suite

CausalLoop operates with 6 distinct tool commands that you can execute at any time:

🔧 Native Tool Integrations

To execute its investigations autonomously, CausalLoop is equipped with 6 custom GitAgent-compliant capabilities defined securely inside the tools/ directory:

• fetch-github-issues.yaml — Pulls live production bugs straight from the GitHub API.
• run-grep-scan.yaml — Invokes ultra-fast C-based grep to search thousands of lines instantly.
• list-directory.yaml — Maps out repository architecture natively.
• read-file.yaml — Ingests application code directly from the filesystem.
• write-file.yaml — Generates permanent Markdown reports of findings.
• run-command.yaml — Executes static analysis testing natively.

📺 Interactive Previews

💻 Welcome Screen & Easy Setup

Start by pointing CausalLoop at any repository URL. It will instantly download it securely and temporarily to begin analyzing.

🎛️ Simple Action Menu

The built-in menu lets you pick exactly which investigation to run.

🩸 1. Codebase Autopsy

Scans for outdated logic, insecure functions, and messy code practices.

🗝️ 2. Password & Key Scanner

Ensures no API keys or database passwords have been left in the text.

🥫 3. Third-Party Audit

Checks your npm or pip files to make sure other people's code isn't breaking yours.

📝 4. Health Check

Verifies you have basic open-source health standards in place (Licenses, Readmes).

🚨 5. Live Bug Interrogation

Connects to GitHub, finds an open bug, and breaks down the real system failure behind it.

🛑 6. Risk Prevention

Looks at newly proposed edits to ensure you don't repeat the errors found in the steps above.

⚡ Installation Guide

CausalLoop is available as a global CLI tool on npm.

Quick Install

npm install -g @vjsharan/causal-loop-agent

Setup & Run

# 1. Go to any project folder on your machine
cd your-project

# 2. Create a .env file containing your free Gemini API key
echo "GOOGLE_API_KEY=your_key_here" > .env

# 3. Run the interactive investigator
causalloop

No cloning needed. Install once, use in any repo.

Option B: gitclaw Runtime Execution

If you prefer to use the gitagent SDK standard execution:

npm install -g gitclaw
gitclaw --dir . --model gemini-2.5-pro "scan this repository for hardcoded secrets"

Option C: Python Standalone Execution

For pure Python inference (requires cloning the repo):

git clone https://github.com/VJsharan/causal-loop-agent.git
pip install -r requirements.txt
python run_lyzr.py --repo "https://github.com/facebook/react" --all

🏛️ Architecture Flow

This map shows how CausalLoop gathers data, thinks about it, and delivers reports.

graph TD
    subgraph "Phase 1: Gathering"
        CLI("User Inputs Link")
    end

    subgraph "Phase 2: Connecting"
        ROUTER("System Decides Action")
        CLONE("Quickly Downloads Code")
        GREP("Scans High-Speed Files")
        API("Reads Web Issues")
    end

    subgraph "Phase 3: The Brain"
        LYZR("Lyzr Safety Guard")
        LLM("Gemini Super-Computer")
    end

    subgraph "Phase 4: Agent Rules"
        SOUL("Personality Profile")
        RULES("Strict Boundaries")
    end

    CLI --> ROUTER
    ROUTER --> CLONE
    CLONE --> GREP
    CLONE --> API
    GREP --> LYZR
    API --> LYZR
    SOUL -.-> LYZR
    RULES -.-> LYZR
    LYZR --> LLM
    LLM --> OUTPUT("Prints Clear Reports to User")

    classDef basic fill:#0f172a,stroke:#3b82f6,stroke-width:2px,color:#f8fafc;
    classDef advanced fill:#1e293b,stroke:#a855f7,stroke-width:2px,color:#f8fafc;
    classDef intelligence fill:#334155,stroke:#10b981,stroke-width:2px,color:#f8fafc;
    classDef guidelines fill:#475569,stroke:#f59e0b,stroke-width:2px,color:#f8fafc;
    
    class CLI basic;
    class ROUTER,CLONE,GREP,API advanced;
    class LYZR,LLM intelligence;
    class SOUL,RULES guidelines;

🧩 Agent Identity Profile

CausalLoop operates based on immutable rules and injected domain knowledge that it will never disobey:

SOUL.md (Who it is)

"I am a forensic systems analyst... I treat 'we didn't know' as a catastrophic engineering failure, not an acceptable excuse."

knowledge/security-patterns.md (What it knows)

The agent's memory bank is pre-injected with modern security patterns, optimizing the model to explicitly hunt for severe security flaws, supply-chain vulnerabilities, and hardcoded secrets with maximum efficiency and speed.

RULES.md (What it must do)

| 🟢 Must Always | 🔴 Must Never | |---------------|--------------| | Find the absolute bottom-level root cause | Pretend the first obvious problem is the whole truth | | Provide exact line numbers as proof | Make guesses without looking at the code | | Predict what could go wrong next based on the past | Blame failure on a human making a mistake |

📌 Project Settings

You can customize how the agent behaves by reading the settings file: agent.yaml.

Ensure you have your environment defined properly as shown in the install step:

• LYZR_API_KEY: Required for agent memory and structure.
• GOOGLE_API_KEY: Required for the AI thinking engine.

📁 File Layout

causal-loop/
├── 🤖 agent.yaml              # The main settings for the agent
├── 🧠 SOUL.md                 # Personality and mood
├── 📏 RULES.md                # Things it is never allowed to do
│
├── 🐍 run_lyzr.py             # Advanced Python scripting engine
├── 📦 index.js                # The visual menu you interact with
├── 🔑 .env                    # Where your passwords live (kept hidden)
│
├── 📁 dummy_repo/             # A safe playground with fake messy code
├── 📁 skills/                 # The 6 investigation techniques
├── 📁 tools/                  # Code that lets it read local files

💻 Technology Stack

| Name | Role | |:---:|:---| | | Defines how the bot is supposed to act | | | Orchestrates the steps and keeps it on track | | | The raw artificial intelligence smarts | | | Used to run it directly from terminal |

👥 Contributing

We love help! If you want to add code to this project, please make sure it aligns with the strict philosophy in the SOUL.md file. Remember: If a test breaks, we fix the test environment. We do not blame the contributor.

⚖️ License

Built for the Lyzr × GitAgent Hackathon 2026 🏆

Fix systems. Not people.