If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Fosowl/agenticSeek shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2w ago
• 14 active contributors
• GPL-3.0 licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Fosowl/agenticSeek repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Fosowl/agenticSeek.

What it runs against: a local clone of Fosowl/agenticSeek — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Fosowl/agenticSeek | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Fosowl/agenticSeek. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Fosowl/agenticSeek.git
#   cd agenticSeek
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Fosowl/agenticSeek and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Fosowl/agenticSeek(\\.git)?\\b" \\
  && ok "origin remote is Fosowl/agenticSeek" \\
  || miss "origin remote is not Fosowl/agenticSeek (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "api.py" \\
  && ok "api.py" \\
  || miss "missing critical file: api.py"
test -f "cli.py" \\
  && ok "cli.py" \\
  || miss "missing critical file: cli.py"
test -f "sources/agents/__init__.py" \\
  && ok "sources/agents/__init__.py" \\
  || miss "missing critical file: sources/agents/__init__.py"
test -f "llm_server/app.py" \\
  && ok "llm_server/app.py" \\
  || miss "missing critical file: llm_server/app.py"
test -f "frontend/agentic-seek-front/src/App.js" \\
  && ok "frontend/agentic-seek-front/src/App.js" \\
  || miss "missing critical file: frontend/agentic-seek-front/src/App.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Fosowl/agenticSeek"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

AgenticSeek is a fully local, privacy-first AI agent framework that autonomously browses the web, writes code, and orchestrates multi-step tasks—all without cloud APIs or external dependencies. It's a self-hosted alternative to Manus AI that runs reasoning models locally, using a modular agent system (web agent, code agent, planning agent) to route tasks intelligently and execute them end-to-end on user hardware. Hybrid monorepo: Python backend (api.py, cli.py, config.ini for agent coordination) paired with a React frontend (frontend/agentic-seek-front with resizable layout, theme context, and markdown rendering). The crx/ folder contains a Nopecha extension for automated CAPTCHA solving. Agents are likely instantiated and routed through api.py based on task intent.

Developers and power users who want autonomous AI capabilities (web scraping, code generation, task automation) without sending data to cloud services, and open-source contributors interested in agentic AI systems, local LLM integration, and agent orchestration patterns.

Experimental/actively-developed: the README explicitly states 'Active Work in Progress' with 'zero roadmap and zero funding,' indicating early-stage but community-driven development. The repo has traction (GitHub Trending), multi-language documentation, and Docker support, but lacks visible CI/CD config (.github/ISSUE_TEMPLATE only, no workflows) and test files, suggesting rapid iteration over stability.

Single-maintainer risk is high (Martin993886460 on Twitter is the sole official update source per README). The Python codebase is substantial (330KB) but no visible pytest/unittest structure, indicating untested or minimally-tested code paths. The project depends on custom local LLM integration (no explicit requirements.txt shown in file list), making dependency version drift and reproducibility concerns real.

Core focus appears to be stabilizing the agent routing system (evident from docs/technical/routing_system.png), building out web and code agent capabilities (web_agent.png, code_agent.png in docs/technical/), and completing voice support ('In progress' per README). Docker Compose and CI infrastructure (Dockerfile.backend, docker-compose.yml) are present but no GitHub Actions workflows visible, suggesting manual deployment.

Clone the repo: git clone https://github.com/Fosowl/agenticSeek.git && cd agenticSeek. Backend: ensure Python 3.x is available (check .python-version), then pip install -r requirements.txt (if exists; else check setup.py). Frontend: cd frontend/agentic-seek-front && npm install. Run API: python api.py from root. Run frontend: npm start from frontend/agentic-seek-front/. Or use Docker Compose: docker-compose up.

Daily commands: Backend: python api.py (or via Docker: docker-compose up). Frontend: cd frontend/agentic-seek-front && npm start (starts React dev server on http://localhost:3000). CLI mode: python cli.py (exact usage undocumented; check source).

• api.py — Main API entry point orchestrating the agentic system; all external requests route through here
• cli.py — CLI interface for local execution; demonstrates how to invoke the agent system without a web server
• sources/agents/__init__.py — Agent module initialization; defines the routing and instantiation of planner, browser, coder, and file agents
• llm_server/app.py — LLM inference server (local Ollama/llama.cpp handler); critical dependency for all model inference
• frontend/agentic-seek-front/src/App.js — React frontend entry point; connects UI to backend API and manages session state
• prompts/base — Base prompt templates for all agent types; modifying these directly affects agent behavior and reasoning
• requirements.txt — Python dependencies; defines core libraries (Selenium, FastAPI, etc.) required for agent execution

Add a new specialized agent

1. Create a new agent class in sources/agents/ (e.g., sources/agents/search_agent.py) inheriting from a base Agent class (sources/agents/search_agent.py)
2. Write system prompt template in prompts/base/ directory (e.g., prompts/base/search_agent.txt) (prompts/base/search_agent.txt)
3. Register the agent in sources/agents/init.py agent factory/router logic (sources/agents/__init__.py)
4. Add a new API endpoint in api.py that routes to the new agent (api.py)
5. Update frontend App.js to expose the new agent in the UI task submission form (frontend/agentic-seek-front/src/App.js)

Switch LLM backend (Ollama to llama.cpp or vice versa)

1. Edit config.ini to change llm_backend setting and model paths (config.ini)
2. Modify llm_server/app.py to load the appropriate handler (ollama_handler or llamacpp_handler) (llm_server/app.py)
3. Update llm_router/config.json if using model routing layer (llm_router/config.json)
4. Restart the llm_server container or process for changes to take effect (docker-compose.yml)

Add a new API endpoint for agent communication

1. Define a new FastAPI route in api.py with appropriate request/response models (api.py)
2. Implement the route handler to call the appropriate agent method from sources/agents/init.py (sources/agents/__init__.py)
3. Add a corresponding axios API call in frontend/agentic-seek-front/src/App.js to consume the new endpoint (frontend/agentic-seek-front/src/App.js)
4. Add UI components in frontend/agentic-seek-front/src/components/ to display results (frontend/agentic-seek-front/src/components/ResizableLayout.js)

Modify agent behavior and reasoning

1. Edit the relevant system prompt in prompts/base/ (e.g., prompts/base/planner_agent.txt) (prompts/base/planner_agent.txt)
2. Optionally adjust agent tuning parameters in config.ini (temperature, max_tokens, etc.) (config.ini)
3. Test agent behavior by submitting tasks via api.py or cli.py and reviewing outputs (api.py)

• FastAPI (Python) — Lightweight async framework enabling concurrent agent handling; native streaming support for real-time result delivery to frontend
• React (TypeScript optional) — Modern frontend for responsive UI; axios integration for seamless API communication with streaming result consumption
• Ollama / llama.cpp — Local-first inference engines eliminating cloud dependency; Ollama provides ease of model management, llama.cpp offers lower-resource inference
• Selenium / Browser Automation — Enables browser agent to perform real web navigation and interactive tasks beyond static API calls
• SearXNG — Privacy-preserving, self-hosted meta-search alternative to external search APIs; avoids provider rate limits and data leakage
• Docker Compose — Multi-container orchestration simplifying local deployment of backend, frontend, and LLM server without manual process management

• Fully local inference (no cloud LLMs like OpenAI/Claude)

  • Why: Ensures data privacy, zero external dependency, and lower operational cost (electricity only)
  • Consequence: Inference latency higher (~2-15s per call vs. <1s cloud); performance dependent on local hardware; reasoning quality limited to locally-available model sizes

• Multi-agent specialization (planner, browser, coder, file agent) vs. single unified agent

  • Why: Allows role-based reasoning optimization and cleaner separation of concerns; reduces hallucination through focused prompting
  • Consequence: Increased orchestration complexity; requires careful routing logic and inter-agent communication; higher total token usage due to repeated context

• Browser automation (Selenium) over headless/API-only browsing

  • Why: Handles JavaScript-heavy sites, CAPTCHAs, and interactive workflows; closer to human web interaction
  • Consequence: Slower browsing (~5-10s per page vs. <1s for raw API); higher resource consumption; brittleness if DOM selectors change

• SearXNG self-hosted vs. API integrations (SerpAPI, Google Search)

  • Why: Full privacy and control; avoids recurring API costs and rate limiting
  • Consequence: Additional infrastructure overhead; requires maintaining SearXNG instance; search quality depends on configured backends

• Does not provide user

No visible requirements.txt or setup.py — infer dependencies from imports in api.py and cli.py; local LLM setup (Ollama? LM Studio?) is likely mandatory but undocumented. config.ini path: ensure it's in the right location before running api.py or cli.py. Nopecha CRX: the crx/ folder suggests Selenium/Playwright-based web automation with CAPTCHA bypass; ensure a browser driver (ChromeDriver, Geckodriver) is installed and in PATH. Docker networking: if running backend and frontend in separate containers, ensure they can communicate (check docker-compose.yml for port mappings). No test suite visible — changes may silently break undocumented behavior.

• Agent Routing / Task Dispatch — AgenticSeek's core innovation is intelligent selection of agents (web vs. code vs. planner) based on user intent; understanding how routing decisions are made is essential to extending the system
• Agentic Loops / ReAct Pattern — Agents operate in think-act-observe cycles to autonomously execute tasks; foundational to how agents break down tasks and refine outputs iteratively
• Web Scraping & Browser Automation (Selenium/Playwright) — The web agent's capability to 'browse the internet by itself' likely uses browser automation; understanding selector strategies, waits, and form filling is critical for extending web capabilities
• Sandboxed Code Execution — The code agent must execute Python/C/Go/Java safely without compromising the host; understanding sandbox strategies (subprocess isolation, containerization, seccomp) is vital for safety
• LLM Token Context Windows & Prompt Engineering — Local reasoning models have limited token budgets and no fine-tuning; effective prompting and context management (deciding what to show the LLM) is critical for task success
• Multi-Agent Orchestration & State Management — Coordinating multiple agents (web, code, planner) to solve a single task requires shared state, handoff protocols, and failure recovery; understanding how api.py maintains context across agent calls is essential
• CAPTCHA Bypass & Browser Extension Integration — The Nopecha CRX extension enables autonomous web interaction; understanding how browser extensions inject scripts and communicate with the automation driver is key to web agent reliability

• geekan/MetaGPT — Multi-agent framework for autonomous software engineering; similar goal of coordinating specialized agents (architect, engineer, reviewer) to execute complex tasks
• langchain-ai/langchain — Agent framework and LLM orchestration library; AgenticSeek likely uses or could integrate LangChain's agent patterns and tool-calling infrastructure
• OpenInterpreter/open-interpreter — Local code execution agent (Python, Bash, JavaScript); overlaps with AgenticSeek's code agent capability and philosophy of client-side-only execution
• Significant-Gravitas/AutoGPT — Foundational autonomous agent framework; precursor to multi-agent systems like AgenticSeek and demonstrates agent reasoning loops
• ollama/ollama — Local LLM runtime that AgenticSeek likely uses for reasoning-model inference; essential companion for the 'fully local' promise

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Python unit tests for llm_router routing logic

The llm_router directory contains a config.json and model files but no visible test coverage. Given this is a critical routing component that directs requests to appropriate LLM models, adding unit tests would catch regressions early. This is especially important for a local-first AI system where model selection directly impacts quality.

• [ ] Create tests/test_llm_router.py with fixtures for config.json loading
• [ ] Add tests for routing decision logic (e.g., model selection based on request type)
• [ ] Test safetensors model loading in llm_router/model.safetensors
• [ ] Add pytest to llm_server/requirements.txt
• [ ] Document test execution in docs/technical or README

Add GitHub Actions CI workflow for multi-platform builds (Python + Node + Docker)

The repo has Dockerfile.backend, Dockerfile.frontend, and docker-compose.yml but no visible CI/CD pipeline. With Python (llm_server), Node (frontend), and Docker components, a matrix CI workflow would catch cross-platform issues early and validate builds on Python 3.8+, Node 18+, and Docker.

• [ ] Create .github/workflows/ci.yml with matrix strategy for [python-version, node-version]
• [ ] Add job for llm_server: pip install -r llm_server/requirements.txt && pytest
• [ ] Add job for frontend: npm install && npm run build in frontend/agentic-seek-front/
• [ ] Add Docker build validation: docker-compose build
• [ ] Include pre-commit checks (.pre-commit-config.yaml is present but not enforced)

Add integration tests for API endpoints in api.py with documented examples

api.py exists but there's no visible test suite validating endpoint behavior. Given this is a core interface between frontend and backend agent logic, adding integration tests would prevent breaking changes and serve as executable documentation for the agent API contract.

• [ ] Create tests/test_api_integration.py using pytest + requests
• [ ] Add fixtures for common payloads (e.g., agent task requests, web browsing commands)
• [ ] Test key endpoints with mocked llm_server responses (avoid heavy model inference in CI)
• [ ] Document test setup in docs/technical/ or CONTRIBUTING.md with example curl commands
• [ ] Ensure tests validate response schemas match frontend expectations (axios calls in App.js)

• Add pytest test suite for api.py: Create tests/test_api.py with test cases for agent routing, task dispatching, and edge cases like invalid agent selection or missing config.ini—currently untested.
• Document config.ini schema and defaults: Create docs/CONFIG_REFERENCE.md with a complete reference of all config.ini keys, their types, example values, and which local LLM setup is required (Ollama vs. LM Studio vs. other)—currently unclear.
• Add missing frontend component tests: Create tests for frontend/agentic-seek-front/src/components/ (e.g., ResizableLayout.test.js, ThemeToggle.test.js) using @testing-library/react; package.json already has testing dependencies but no tests present.

• High · Sensitive API Keys in .env.example — .env.example. The .env.example file contains placeholder values for multiple API keys (OPENAI_API_KEY, DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, etc.). While these are examples, developers may accidentally commit actual keys or use this file as a template without properly sanitizing secrets. Fix: Ensure .env and .env.local are in .gitignore (verify in .gitignore). Document that developers must NEVER commit actual API keys. Use a secrets management system for production deployments. Consider using AWS Secrets Manager, HashiCorp Vault, or similar tools.
• High · Potential React XSS via react-markdown — frontend/agentic-seek-front/package.json. The project uses react-markdown (^10.1.0) which can render user-generated content. If markdown content comes from untrusted sources without proper sanitization, it could enable XSS attacks. The version constraint allows minor/patch updates which may introduce vulnerabilities. Fix: Ensure react-markdown is used with the 'skipHtml' option enabled by default. Validate and sanitize all markdown input before rendering. Consider using react-markdown with rehype-sanitize plugin for additional XSS protection. Pin versions explicitly for security-critical dependencies.
• High · Insecure Docker Network Configuration — docker-compose.yml. The docker-compose.yml shows services on the same network (agentic-seek-net) with minimal network segmentation. The searxng service exposes port 8080 publicly, and there's no explicit network policies or service-to-service authentication enforced. Fix: Implement network policies between services. Restrict searxng port exposure to internal network only unless external access is required. Add authentication/authorization between microservices. Use Docker secrets for sensitive data instead of environment variables.
• High · Overly Permissive Logging Configuration — docker-compose.yml (redis and searxng services). Docker services are configured with json-file logging driver with max-size of only 1m and max-file of 1. This minimal logging could lose important security events and audit trails, and logs may contain sensitive information without retention policies. Fix: Implement comprehensive logging strategy with appropriate retention. Use centralized logging (ELK, Splunk). Sanitize logs to prevent leaking sensitive data. Increase log rotation limits for production. Implement log monitoring and alerting for security events.
• Medium · Missing CORS Configuration — api.py (backend) and frontend configuration. Frontend communicates with backend at REACT_APP_BACKEND_URL (http://localhost:7777). No visible CORS configuration in the provided snippets. This could allow unintended cross-origin requests or be too permissive if misconfigured. Fix: Implement strict CORS policy in the backend (api.py) to only allow requests from known frontend origins. Use whitelist-based approach. Set appropriate headers (Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Credentials).
• Medium · Potential Arbitrary File Access via WORK_DIR — .env.example (WORK_DIR configuration). The WORK_DIR environment variable (set to user's workspace) is used by the application. If the backend doesn't properly validate file paths, this could enable Local File Inclusion (LFI) or arbitrary file read/write attacks through path traversal. Fix: Implement strict path validation in file operations. Use a whitelist of allowed directories. Prevent path traversal by validating against '..' and absolute paths. Use os.path.realpath() and ensure resolved path is within allowed WORK_DIR. Implement file access controls.
• Medium · Unversioned Dependency Constraints — frontend/agentic-seek-front/package.json. Dependencies use flexible versioning (e.g., '^1.8.4', '^5.0.1'). This allows automatic updates to potentially vulnerable versions. react-scripts 5.0.1 is noted as having known vulnerabilities in some configurations. Fix: Use npm ci instead of npm install in production. Pin versions explicitly for critical dependencies. Regularly run npm audit and address vulnerabilities. Implement dependency scanning in CI/CD pipeline. Use tools like Dependabot or Snyk for automated vulnerability detection.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.