When a plane crashes, investigators don't just blame the pilot—they fix the training, the gauges, and the rules. CausalLoop investigates your code the exact same way.
- What is CausalLoop?
- Live Demo
- Agent Features
- Live Tools Suite
- Interactive Previews
- Installation Guide
- Architecture Flow
- Agent Identity Profile
- Project Settings
- File Layout
- Technology Stack
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.
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 |
CausalLoop operates with 6 distinct tool commands that you can execute at any time:
 Scans the legacy codebase for security vulnerabilities |
 Hunts credentials & active private keys |
 Validates supply-chain architecture |
 Audits institutional git hygiene |
 Fetches live GitHub bugs & runs Five Whys |
 Pre-merge warnings on incoming PR diffs |
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.
Click above to watch the full project demonstration!
Start by pointing CausalLoop at any repository URL. It will instantly download it securely and temporarily to begin analyzing.
The built-in menu lets you pick exactly which investigation to run.
Scans for outdated logic, insecure functions, and messy code practices.
Ensures no API keys or database passwords have been left in the text.
Checks your npm or pip files to make sure other people's code isn't breaking yours.
Verifies you have basic open-source health standards in place (Licenses, Readmes).
Connects to GitHub, finds an open bug, and breaks down the real system failure behind it.
Looks at newly proposed edits to ensure you don't repeat the errors found in the steps above.
CausalLoop is available as a global CLI tool on npm.
npm install -g @vjsharan/causal-loop-agent# 1. Get a free Gemini API key at https://aistudio.google.com
# 2. Go to any git repo
cd your-project
# 3. Create a .env file with your key
echo "GOOGLE_API_KEY=your_key_here" > .env
# 4. Run the investigator
causalloopTip
No cloning needed. Install once, use in any repository globally.
If you are already integrated with the GitAgent ecosystem:
npm install -g gitclaw
gitclaw --dir . --model gemini-2.5-pro "scan this repository for hardcoded secrets"For contributors or standalone forensic inference:
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
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;
CausalLoop operates based on immutable rules and injected domain knowledge that it will never disobey:
"I am a forensic systems analyst... I treat 'we didn't know' as a catastrophic engineering failure, not an acceptable excuse."
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.
| 🟢 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 |
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.
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
| 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 |
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.
Built for the Lyzr × GitAgent Hackathon 2026 🏆
Fix systems. Not people.