Technical Briefing: n8n-claw

The Problem

Organizations needing autonomous AI capabilities often face fragmented solutions requiring multiple specialized tools, each with its own infrastructure, authentication model, and data silos. Teams building self-hosted agents must independently solve memory persistence, skill composition, agent delegation, and monitoring — problems n8n-claw addresses as a unified framework but one that carries operational and legal overhead from its current state.

What This Does

n8n-claw is a self-hosted AI agent framework built on n8n + PostgreSQL, providing Telegram and webhook API integration, adaptive RAG-powered memory with hybrid search and time-decay, a knowledge graph for multi-hop entity tracking, task management with proactive heartbeats, and expert agent delegation via MCP templates. The codebase comprises 69 files across 5 sub-projects: supabase (10 SQL migration files, 4 seed datasets), browser-bridge (4 Python files driving Chromium automation via Browser Use), discord-bridge (1 bot.js), email-bridge (1 server.js), and file-bridge (1 server.js). Seventeen workflow JSON files in workflows/ encode the agent's reasoning loops, memory consolidation, sub-agent runner, and heartbeat logic. Entry points are browser-bridge/src/main.py, email-bridge/server.js, and file-bridge/server.js. The system supports web search via embedded SearXNG, web reading through Crawl4AI, and 100+ expert agents from the n8n-claw-agents catalog.

How It Is Wired

Execution originates at browser-bridge/src/main.py (Python, 0 importers, 2 importers — instability index 1), which initializes the session pool (browser-bridge/src/session_pool.py) and LLM bridge (browser-bbridge/src/llm.py). The LLM module has 1 importer and 0 outbound edges, making it a terminal dependency in the import graph. The session pool has 1 importer and 0 outbound edges. Both modules contain bare except clauses that swallow errors indiscriminately (measured finding: resilience concern). The setup.sh file at 2,484 lines is an oversized single-responsibility unit — a change here ripples widely across the system. The utils/upgrade-pg17.sh script has 88 branch points over 298 lines, indicating high branching density that should be decomposed. The import graph contains 7 internal modules and 2 import edges with zero circular dependencies across the 9 analyzed files. Outside the code, 17 workflow JSON files interface with n8n's execution engine; the Supabase migrations handle schema evolution, RAG search, and MCP bridge logic. The Dockerfiles (browser-bridge, discord-bridge, email-bridge) build runtime images but lack a USER directive, running as root by default.

How To Use It

Setup: The repository includes a setup.sh script (2,484 lines) referenced in LOCAL_SETUP.md. Docker Compose is defined in docker-compose.yml. No lockfiles are committed for Python (browser-bridge/requirements.txt) or Node (discord-bridge/package.json, email-bridge/package.json, file-bridge/package.json), so pip install and npm ci may resolve different transitive versions across runs.

Configuration: Environment variables are documented in .env.example. Required secrets include Telegram bot tokens, Claude API keys, and Supabase connection strings. The Supabase schema is initialized via the 10 migration files in supabase/migrations/.

Running it: Start the stack with docker-compose up -d. The n8n workflow engine hosts the agent logic; the bridges (browser, email, file, discord) connect external systems via their respective entry points. No CLI entry point beyond the n8n UI is exposed — interaction occurs through Telegram or the webhook API.

Real-World Use

A marketing team connects their Telegram channel to n8n-claw. The agent monitors for weekly briefing requests, uses its knowledge graph to recall prior campaign metrics, invokes the "content creation" expert sub-agent via MCP, and drafts a post — all while logging any workflow errors to memory and notifying the team via Telegram. The team can ask "did anything fail today?" and the agent explains the last background check error in plain language without requiring log excavation.

Code Health & Issues

The static analysis produced 8 findings across 5 severity tiers:

  • [HIGH] Add a LICENSE — no licence file at root; default is all rights reserved, blocking reuse in client engagements. Fix: add MIT or Apache-2.0 at repository root.
  • [HIGH] Commit a lockfile — discord-bridge/package.json has no lockfile; unlocked ranges risk shipping different transitive code than tested. Fix: run the package manager once and commit the generated lockfile.
  • [MEDIUM] Declare least-privilege GITHUB_TOKEN permissions — .github/workflows/mirror-to-codeberg.yml declares no permissions despite referencing secrets. Fix: add permissions: contents: read at the top of the workflow.
  • [MEDIUM] Enable Dependabot or Renovate — 4 manifests with no update bot configured. Fix: commit .github/dependabot.yml covering Python, Node, and github-actions ecosystems.
  • [MEDIUM] Pin container base image by digest — browser-bridge/Dockerfile uses python:3.12-slim without a digest. Fix: use python:3.12-slim@sha256:<digest> and enable Dependabot's docker ecosystem.
  • [MEDIUM] Gate pull requests on dependency vulnerability scan — no dependency scan in CI. Fix: add dependency-review-action on pull_request or osv-scanner on push/schedule.
  • [MEDIUM] Add non-root USER to browser-bridge image — Dockerfile has no USER directive; root process against mounted volumes is a host exposure risk. Fix: create unprivileged user, chown needed paths, end Dockerfile with USER.
  • [LOW] Set timeout-minutes on workflow jobs — mirror-to-codeberg.yml has no job timeout; a wedged step runs to the six-hour default. Fix: add realistic timeout-minutes per job.

The Bottom Line

n8n-claw delivers a capable, self-hosted AI agent framework with genuine utility for teams wanting Telegram- or API-integrated autonomy, memory, and skill composition without third-party SaaS constraints. The codebase is functional but carries significant operational risk: no licence means unclear redistribution rights, dependencies lack lockfiles for reproducibility, and several Dockerfiles/CI configs run with elevated privileges. Teams comfortable self-hosting and managing these hygiene gaps will find real value; those needing out-of-the-box compliance and reproducibility should look elsewhere or budget the fix time upfront.