Jarvis

A fully automated agent system that lives on a server. Will always run, can be started, stopped, restarted. Autorestarts on crash and can be configured via a setup phase. This README is the entry point and links to focused docs for each major topic.

Docs

• Onboarding and Configuration: docs/setup.md
• CLI and Server Lifecycle: docs/cli.md
• Agent system details: docs/agent.md
• UI implementation: docs/ui.md
• Evaluation guide: docs/evaluation.md

Principles (early draft)

• Minimal surface area in v1
• Clear defaults and predictable behavior
• Simple local data model
• No hidden automation

end goal (how i wish the system will be onced finished)

• following what jarvis is doing is super easy to understand for a human
• everything that goes wrong e.g. failed tool calls, or errors from exec calls should be easy to understand for a human
• transparency is very important, without this we can not easily debug or improve the system
• it should work autonomously, i.e. it does not need any instructions from me on decicions but instead decide itself how to achieve whatever its doing
• when working autonomously on a task its given it should know when to stop (task is done in a good quality)

Implementation Roadmap

To reach v1, we will follow this order:

1. Phase 1: Project Skeleton [x]
   • Scaffolding (package.json, folder structure).
   • Basic HTTP server on port 18008.
2. Phase 2: Onboarding & Config [x]
   • jarvis setup CLI command.
   • Persistence for API keys (.env) and settings (settings.json).
3. Phase 3: Core Agent Loop [x]
   • Request/Response flow with OpenRouter.
   • Serial tool execution logic (new Function).
   • Basic session persistence.
   • Seed tool: list_dir (runs ls -la) to verify the full loop end-to-end.
4. Phase 4: Lifecycle Management [x]
   • CLI start/stop/status using programmatic PM2.
   • Pre-flight configuration checks.
5. Phase 5: Tools & Refinement [x]
   • Implementation of built-in tools (exec, user_info).
   • Standardized logging (JSONL).
6. Phase 6: UI [x]
   • Vite + React + Tailwind chat interface in ui/.
   • Server serves built UI as static files.

Usage

First-time setup

npm install
npm run setup

This prompts for your OpenRouter API key and model selection.

Running in production (background via PM2)

npm start          # start the server in the background (auto-restarts on crash)
npm run status     # check if it's running (PID, uptime, restarts)
npm run stop       # stop the background server

The server runs on port 18008. Open http://localhost:18008 to use the chat UI.

Logs are written to ~/.jarvis/logs/server.log.

Running in development (foreground)

npm run dev        # start the server with nodemon (auto-reload on file changes)

To develop the UI with hot-reload:

cd ui
npm install        # first time only
npm run dev        # starts Vite on port 5173, proxies /api to localhost:18008

You need both the server (npm run dev in root) and the UI dev server (npm run dev in ui/) running at the same time. Open http://localhost:5173 during UI development.

Building the UI for production

cd ui
npm run build

This outputs to ui/dist/, which the Express server serves as static files automatically.

Global install

npm i -g @ducci/jarvis
jarvis setup
jarvis start
jarvis stop
jarvis status

Security & Local Usage

Jarvis is designed for local use only. There is no built-in authentication for the API. It is intended to be run on a trusted machine (e.g., your laptop or a private server) where the port is not exposed to the public internet.

Current status, IMPORTANT instructions for LLMs:

• Phase 1 (Skeleton) is implemented.
• Phase 2 (Onboarding & Config) is implemented.
• Phase 3 (Core Agent Loop) is implemented.
• Phase 4 (Lifecycle Management) is implemented.
• Phase 5 (Tools & Refinement) is implemented.
• Phase 6 (UI) is implemented.
• the scope is only this jarvis folder and each file in it. no parent folders or any other outside of this