hive-am 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to hive-am are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-09
+
+### Added
+
+- Agent manager over Claude Code, OpenCode and Kiro, resuming each CLI's native session.
+- Orchestrators and subagents: explicit delegation, with a new subagent session for every task.
+- Colonies with optional inheritance of folder, permissions, skills and context; honeycomb map, agent types and relations canvas.
+- Skills loaded always or on demand (per assignment), with seven skills included.
+- Agent notebook: its own memory, readable and editable from the interface.
+- Telegram connection: private chats, groups and topics, per-thread silence, files and images in both directions and an optional image model.
+- Three permission levels (read-only, edit files and full access) enforced by the CLI itself in all three providers.
+- Git changes explorer: tree, diffs, history, commit, pull, push, branches, conflicts, stashes, blame and discarding changes.
+- Interface in English and Spanish, with light and dark themes.
+- Complete documentation in English and Spanish.
+- npm package with the `hive-am` command.
+
+[Unreleased]: https://github.com/hughcbscrt/hive-am/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/hughcbscrt/hive-am/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Hernández Valdez
+
+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

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="web/public/logo.png" alt="hive-am" width="180" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">hive-am</h1>
+
+<p align="center">
+  <strong>A colony of coding agents on your machine.</strong><br />
+  Orchestrators and subagents over <b>Claude Code</b>, <b>OpenCode</b> and <b>Kiro</b>, with the real sessions of each CLI, a browser UI and Telegram.
+</p>
+
+<p align="center">
+  <a href="https://github.com/hughcbscrt/hive-am/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
+  <a href="https://github.com/hughcbscrt/hive-am/pulls?q=is%3Apr"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr-closed/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
+  <a href="https://github.com/hughcbscrt/hive-am/issues"><img alt="Issues" src="https://img.shields.io/github/issues/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
+  <a href="https://github.com/hughcbscrt/hive-am"><img alt="Repo size" src="https://img.shields.io/github/repo-size/hughcbscrt/hive-am?style=flat-square&color=bf963d" /></a>
+  <a href="https://github.com/hughcbscrt/hive-am"><img alt="Top language" src="https://img.shields.io/github/languages/top/hughcbscrt/hive-am?style=flat-square&color=3178c6" /></a>
+  <img alt="Node 20+" src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=nodedotjs&logoColor=white" />
+  <img alt="Next.js 15" src="https://img.shields.io/badge/Next.js-15-000000?style=flat-square&logo=nextdotjs&logoColor=white" />
+  <img alt="SQLite" src="https://img.shields.io/badge/SQLite-local-003B57?style=flat-square&logo=sqlite&logoColor=white" />
+</p>
+
+---
+
+hive-am lets you create **orchestrators** and **subagents**, group them into **colonies**, give them **skills** and a **notebook**,
+talk to them from the browser or from **Telegram**, and see everything they did, even after a blackout. It runs the CLIs you already
+have installed; it does not replace them and it never copies your conversations into its own database.
+
+## Highlights
+
+- **Three providers, one place.** Claude Code, OpenCode and Kiro agents side by side, each with its own model.
+- **Real sessions.** An agent stores only a pointer (`provider`, `session_id`, `cwd`). The transcript lives in the CLI's own store and is read back from there. After a restart every agent resumes its real session.
+- **Orchestration.** An orchestrator delegates to the workers connected to it on the Relations canvas. Every delegation runs in a fresh native session of the worker, and the rule is enforced on the server, not just requested.
+- **Colonies.** Group agents on a honeycomb map and lend them defaults: working folder, permissions, skills and a shared prompt. Each agent can opt out per field.
+- **Skills.** Seven general skills ship with hive-am (all ordinary: edit or delete them). Assign them to an agent, a type or a colony, and choose per assignment whether they are **always** in the instructions or loaded **on demand** with a `skill_read` tool. Searchable picker with token weights.
+- **Notebook.** An agent can keep a persistent notebook of what it learns (no credentials, no duplicates, every note with its source). You can read and edit it from the agent's settings.
+- **Telegram.** Link a bot to an agent: private chats, groups and topics, one shared session across all of them. In groups the agent can listen to everything and speak only when it adds something; people can mute it per thread and bring it back.
+- **Files and images.** People send documents and photos to the agent; the agent sends files back. An optional image model can describe pictures for models that cannot see them.
+- **Permissions that hold.** *Read-only*, *Edit files* and *Full access* are enforced by the CLI itself in all three providers.
+- **Changes explorer.** A Git tab per agent: file tree with highlighting, diff viewer, history, commit, pull, push and branches.
+- **Local and private.** The server binds to `127.0.0.1`. Data lives in `~/.hive-am/`.
+
+## Providers
+
+| Provider | Run a turn | Transcript source |
+|---|---|---|
+| Claude Code | `claude -p --output-format stream-json --resume <id>` | `~/.claude/projects/*/<id>.jsonl` |
+| OpenCode | `opencode run --format json -s <id>` | `~/.local/share/opencode/opencode.db` (`session_message`) |
+| Kiro | `kiro-cli chat --no-interactive --output-format stream-json --resume-id <id>` | `~/.kiro/sessions/cli/<id>.jsonl` |
+
+Plain CLI processes, one per turn, not ACP. Turns are serialized per agent.
+
+## Quick start
+
+You need Node 20+ and at least one of the three CLIs installed and logged in.
+
+```bash
+git clone git@github.com:hughcbscrt/hive-am.git
+cd hive-am
+npm install
+npm run dev        # server :4400 (API + WebSocket) and Next.js UI :4401
+```
+
+Open <http://127.0.0.1:4401>, create an agent pointing at a folder, and send it a message.
+
+Data lives in `~/.hive-am/hive-am.db` (override with `HIVE_AM_HOME`). The server only listens on `127.0.0.1`.
+
+## Permission levels
+
+| Level | Claude Code | OpenCode | Kiro |
+|---|---|---|---|
+| **Read-only** | `--permission-mode plan` | edit, shell and subagents denied | no tool trusted |
+| **Edit files** | `acceptEdits`, `.git` and keys protected | edits (`.env` included), no shell, only inside the agent's folder | same |
+| **Full access** | `bypassPermissions` | no restrictions | `--trust-all-tools` |
+
+In *Edit files* the agent cannot touch `.git` or private keys (`*.pem`, `*.key`) and cannot write outside its folder. Details and the
+few differences between providers are in [docs/06](docs/reference/en/06-providers.md) and [docs/12](docs/reference/en/12-operations-and-troubleshooting.md).
+
+## Connections (Telegram)
+
+1. Create a bot with @BotFather and copy its token.
+2. In **Connections**, add a Telegram connection, pick the agent that answers, and list the people (and groups) allowed to talk to it.
+3. Optional: set the group mode (`mention` or `open`), an alias, whether files are accepted, and an image model.
+
+The agent answers through a `channel_reply` tool: its plain text is never delivered. Only authorized people and groups reach it,
+checked on the server. The bot token is stored in `~/.hive-am/hive-am.db` and never returned by the API; see the note about it in
+[docs/14](docs/reference/en/14-external-connections.md).
+
+## How it is built
+
+- `server/`: TypeScript. SQLite entities, provider runners, native history readers, the per-agent turn queue, REST and WebSocket.
+  - `src/instructions.ts`: what each agent is told (identity, skills, team, channels, notebook) and which hive tools it gets.
+  - `src/connections/`: external connections. One agent session shared by every chat, group or topic.
+  - `src/skills/`: the skills that ship with hive-am and the agent notebook.
+  - `mcp/dispatch.mjs`: the `hive` MCP server: `list_agents` and `dispatch` for orchestrators, `channel_*` for connections, `notebook_*` and `skill_read`.
+- `web/`: Next.js 15 UI. Colony (honeycomb), Agents, the agent workspace (chat, changes, settings, notebook, sessions), Relations canvas, Types, Skills, Connections and Sessions.
+
+## Documentation
+
+Full documentation in English and Spanish: **[English](docs/reference/en/README.md)** · **[Español](docs/reference/es/README.md)**.
+
+| Topic | Where |
+|---|---|
+| Overview and architecture | [docs/01](docs/reference/en/01-overview.md) |
+| Folder structure | [docs/02](docs/reference/en/02-project-structure.md) |
+| Storage and database | [docs/04](docs/reference/en/04-storage.md) |
+| Providers and permissions | [docs/06](docs/reference/en/06-providers.md) |
+| Agents, types, skills and colonies | [docs/07](docs/reference/en/07-agents-types-skills-colonies.md) |
+| Orchestration and relations | [docs/09](docs/reference/en/09-orchestration-and-relations.md) |
+| Changes explorer (git) | [docs/13](docs/reference/en/13-changes-explorer-git.md) |
+| External connections | [docs/14](docs/reference/en/14-external-connections.md) |
+| Operation and troubleshooting | [docs/12](docs/reference/en/12-operations-and-troubleshooting.md) |
+
+## Known limits
+
+- Claude fixes the system prompt when a session starts, so changed instructions reach a resumed session as an update inside the next message (OpenCode and Kiro get them the same way).
+- A turn in flight during a crash is lost; the session is intact and the agent is idle on restart.
+- Instructions are advice to the model; what the server enforces is who an agent can delegate to, who a connection answers, which files can be sent, and the permission level.
+- There is no automated test suite. Features are checked with simulations against real agents (`server/scripts/sim-*.ts`).

package/bin/hive-am.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// hive-am launcher: starts the API server and the web UI from the published package.
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const args = process.argv.slice(2);
+
+const HELP = `hive-am ${pkg.version}
+${pkg.description}
+
+Usage:
+  hive-am [start]        start the server (API + WebSocket, port 4400) and the web UI (port 4401)
+  hive-am --version      print the version
+  hive-am --help         show this help
+
+Environment:
+  HIVE_AM_HOME           data folder (default ~/.hive-am)
+  HIVE_AM_WEB_PORT       port of the web UI (default 4401)
+
+The API server always uses port 4400: the packaged UI is built to talk to it.
+Requires Node >= ${pkg.engines?.node?.replace('>=', '') ?? '20'} and at least one of the CLIs installed and logged in: claude, opencode, kiro-cli.`;
+
+if (args.includes('--help') || args.includes('-h')) { console.log(HELP); process.exit(0); }
+if (args.includes('--version') || args.includes('-v')) { console.log(pkg.version); process.exit(0); }
+if (args.length && args[0] !== 'start') { console.error(`Unknown command: ${args[0]}\n\n${HELP}`); process.exit(1); }
+
+if (process.env.HIVE_AM_PORT && process.env.HIVE_AM_PORT !== '4400') {
+  console.error('HIVE_AM_PORT is not supported by the packaged build: the UI is built to talk to the API on port 4400.');
+  process.exit(1);
+}
+
+const webPort = process.env.HIVE_AM_WEB_PORT ?? '4401';
+const next = join(dirname(createRequire(import.meta.url).resolve('next/package.json')), 'dist', 'bin', 'next');
+
+const children = [
+  spawn(process.execPath, [join(root, 'server', 'dist', 'index.js')], { cwd: join(root, 'server'), stdio: 'inherit' }),
+  spawn(process.execPath, [next, 'start', '-p', webPort, '-H', '127.0.0.1'], { cwd: join(root, 'web'), stdio: 'inherit' }),
+];
+
+let closing = false;
+const stop = (code = 0) => {
+  if (closing) return;
+  closing = true;
+  for (const c of children) c.kill('SIGTERM');
+  setTimeout(() => process.exit(code), 500).unref();
+};
+for (const c of children) c.on('exit', (code) => { if (!closing) { console.error('hive-am: a process exited, stopping.'); stop(code ?? 1); } });
+process.on('SIGINT', () => stop(0));
+process.on('SIGTERM', () => stop(0));
+setTimeout(() => console.log(`\nhive-am is running → http://127.0.0.1:${webPort}  (API on 127.0.0.1:4400)`), 2500).unref();

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "hive-am",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A colony of coding agents: orchestrators and subagents over Claude Code, OpenCode and Kiro, with real session resume, a browser UI and Telegram.",
+  "keywords": [
+    "ai-agents",
+    "coding-agents",
+    "agent-manager",
+    "orchestrator",
+    "subagents",
+    "claude-code",
+    "opencode",
+    "kiro",
+    "telegram",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://github.com/hughcbscrt/hive-am#readme",
+  "bugs": {
+    "url": "https://github.com/hughcbscrt/hive-am/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hughcbscrt/hive-am.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hugo Hernández Valdez",
+    "url": "https://github.com/hughcbscrt"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "type": "module",
+  "bin": {
+    "hive-am": "bin/hive-am.mjs"
+  },
+  "files": [
+    "bin",
+    "server/dist",
+    "server/mcp",
+    "server/package.json",
+    "web/.next",
+    "web/public",
+    "web/next.config.mjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.11.1",
+    "ws": "^8.21.3",
+    "@xyflow/react": "^12.3.0",
+    "highlight.js": "^11.12.0",
+    "lucide-react": "^0.468.0",
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  }
+}