jarvis-ai-agent 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+TELEGRAM_BOT_TOKEN=
+CODEX_MODEL=
+POLL_TIMEOUT_SECONDS=30
+MAX_REPLY_CHARS=3500
+USER_TIMEZONE=Africa/Lagos
+SCHEDULER_INTERVAL_MS=15000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Youssef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Jarvis AI Agent
+
+This folder contains a Telegram long-polling bot that listens for text messages, asks a selected local AI CLI to draft a response, and sends the reply back to the user.
+
+Jarvis now keeps its own local user profiles, saved memories, recent conversation context, and scheduled reminder tasks.
+
+## Install
+
+From npm after publish:
+
+```sh
+npm install -g jarvis-ai-agent
+jarvis-agent
+```
+
+From a public GitHub repo before publish:
+
+```sh
+npm install -g github:<owner>/jarvis-ai-agent
+jarvis-agent
+```
+
+To stop a running instance:
+
+```sh
+jarvis-agent-stop
+```
+
+## Files
+
+- `bot.js`: main polling service
+- `start-jarvis.js`: portable Node bootstrapper
+- `stop-jarvis.js`: portable Node stopper
+- `build-shareable.js`: creates a clean copy without secrets or local runtime state
+- `skills/`: project-local custom skills that are synced into the global Codex home on startup
+- `scripts/install-local-skill.js`: installs a skill folder into this agent's local `skills/` directory
+- `.env`: local configuration
+- `.env.example`: starter configuration template for a fresh machine
+- `data/jarvis-store.json`: local user profiles, memory, and scheduled tasks
+
+## Start it
+
+Open a terminal in this folder and run:
+
+```sh
+npm start
+```
+
+To stop it:
+
+```sh
+npm stop
+```
+
+To create a clean copy for another computer:
+
+```sh
+npm run share
+```
+
+The package also exposes matching global commands:
+
+```sh
+jarvis-agent
+jarvis-agent-stop
+jarvis-agent-share
+```
+
+## Install On Another Computer
+
+1. Install Node.js 18 or newer.
+2. Install Codex CLI.
+3. Run `codex login` on that computer.
+4. Install Jarvis with `npm install -g jarvis-ai-agent` or `npm install -g github:<owner>/jarvis-ai-agent`.
+5. Go to the installed package directory if you want to edit `.env` in place, or clone the repo and run it locally.
+6. Copy `.env.example` to `.env`.
+7. Set `TELEGRAM_BOT_TOKEN` in `.env`.
+8. Run `jarvis-agent`.
+
+## Notes
+
+- Only text messages are handled right now.
+- Replies are generated through the currently selected CLI tool for that chat: Codex CLI, Claude CLI, or OpenCode CLI.
+- Jarvis uses the global Codex config (`~/.codex`). Skills are synced into `~/.codex/skills/jarvis-local` on every start.
+- User memory and tasks are stored locally in `data/jarvis-store.json`.
+- Telegram polling restart state is stored in `data/runtime-state.json`.
+- Secrets and machine-specific state are listed in `.gitignore` so they are easier not to share by accident.
+- `npm run share` creates a sibling folder ending in `-shareable` without `.env`, logs, and runtime state files.
+- npm package binaries are `jarvis-agent`, `jarvis-agent-stop`, `jarvis-agent-share`, and `jarvis-agent-install-skill`.
+
+## Commands
+
+- `/start_agent`
+- `/end_agent`
+- `/model`
+- `/new`
+- `/restart`
+- `/help`
+- `/skills`
+- `/profile`
+- `/profile set <key> <value>`
+- `/remember <fact>`
+- `/memories`
+- `/forget <memory-id>`
+- `/schedule YYYY-MM-DD HH:mm | task`
+- `/tasks`
+- `/done <task-id>`
+
+## Agent Mode
+
+- Jarvis only answers free-form AI requests after you send `/start_agent`.
+- Send `/end_agent` to stop AI replies for that user chat.
+- Send `/model` to open a Telegram button flow and choose Codex CLI, Claude CLI, or OpenCode CLI for that chat.
+- If you choose OpenCode CLI, Jarvis will load the full `opencode models` list from the terminal and let you browse all available models in Telegram before using it.
+- Send `/new` to clear the recent conversation context for that chat while keeping profile, memories, tasks, and the selected CLI tool.
+- Send `/restart` to restart the bot through the launcher.
+- Command messages like `/help`, `/profile`, `/tasks`, and memory commands still work even when AI replies are off.
+
+## Skills
+
+- Local skills live in `skills/` inside the agent directory.
+- On startup, `start-jarvis.js` copies those skills into `~/.codex/skills/jarvis-local` so Codex can use them.
+- Use `/skills` in Telegram to see the installed local skills.
+- Each skill also becomes a slash command automatically after restart.
+- Skill commands use underscores, for example `/coding_helper`.
+- Selecting a skill command runs that skill immediately.
+- You can also pass input with the command, for example `/coding_helper fix this Python error`.
+- The starter pack includes `Assistant Core`, `Coding Helper`, `Research Helper`, `Task Manager`, and `Writing Helper`.
+- A local `Skill Installer` skill is included too, along with `scripts/install-local-skill.js` for project-local skill installs.

package/bin/jarvis-agent-install-skill.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../scripts/install-local-skill.js");

package/bin/jarvis-agent-share.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../build-shareable.js");

package/bin/jarvis-agent-stop.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../stop-jarvis.js");

package/bin/jarvis-agent.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+"use strict";
+
+require("../start-jarvis.js");