{"_id":"@agenticros/followme","name":"@agenticros/followme","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@agenticros/followme","version":"0.2.0","type":"module","description":"Follow Me skill for AgenticROS — depth-based (optionally Ollama-VLM-assisted) person following with turn-to-track and search-when-lost.","keywords":["agenticros","ros2","robotics","follow","person-following","navigation","depth","ollama"],"homepage":"https://github.com/agenticros/agenticros-skill-followme#readme","bugs":{"url":"https://github.com/agenticros/agenticros-skill-followme/issues"},"repository":{"type":"git","url":"git+https://github.com/agenticros/agenticros-skill-followme.git"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"agenticros":{"id":"followme","displayName":"Follow Me","description":"Depth-based person following with optional Ollama / VLM, turn-to-follow, and search-when-lost behaviors. The reference implementation of the skill contract.","categories":["navigation","human-interaction","vision"],"capabilities":[{"id":"follow_robot","verb":"follow","description":"Drive forward while keeping a safe distance from whatever is in front of the camera (closed-loop on depth).","interruptible":true,"blocks_base":true},{"id":"follow_me_see","verb":"see","description":"Take a snapshot and ask the local Ollama VLM what's in front of the robot — useful for verifying the follow target.","interruptible":true,"blocks_base":false},{"id":"ollama_status","verb":"diagnose","description":"Report whether the local Ollama server is reachable and which vision model is installed.","interruptible":false,"blocks_base":false}]},"dependencies":{"@agenticros/core":"^0.8.0","@sinclair/typebox":"^0.34.0"},"devDependencies":{"@types/node":"^20.17.0","typescript":"^5.7.0"},"author":{"name":"PlaiPin"},"license":"Apache-2.0","publishConfig":{"access":"public"},"_id":"@agenticros/followme@0.2.0","gitHead":"a39004cdc94fafd41ebfdc417644b4c04db081f0","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-EaSaa8vBSspmSmUuv9omikLqMfb/2YTolHyyfMhRsNdYFZsWlSe3ELQ2fZ+0BaAOtd7iWCeK/vgKsgHduYYJPA==","shasum":"6f25568bf8461217f505eb7ce9cd02fb8c0cf47d","tarball":"https://registry.npmjs.org/@agenticros/followme/-/followme-0.2.0.tgz","fileCount":34,"unpackedSize":95150,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHwGMYG1Wxw7ODf7c+GoK5SOcm7hXwP01/GIcTM+ZqntAiAXOyW/79B8LAr1BFSEmt5Xy9CIaikXSyIyuwnQZvzfOA=="}]},"_npmUser":{"name":"chrismatthieu","email":"chris@matthieu.us"},"directories":{},"maintainers":[{"name":"chrismatthieu","email":"chris@matthieu.us"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/followme_0.2.0_1783638143194_0.5822811817276512"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T23:02:23.034Z","0.2.0":"2026-07-09T23:02:23.342Z","modified":"2026-07-09T23:02:23.613Z"},"maintainers":[{"name":"chrismatthieu","email":"chris@matthieu.us"}],"description":"Follow Me skill for AgenticROS — depth-based (optionally Ollama-VLM-assisted) person following with turn-to-track and search-when-lost.","homepage":"https://github.com/agenticros/agenticros-skill-followme#readme","keywords":["agenticros","ros2","robotics","follow","person-following","navigation","depth","ollama"],"repository":{"type":"git","url":"git+https://github.com/agenticros/agenticros-skill-followme.git"},"author":{"name":"PlaiPin"},"bugs":{"url":"https://github.com/agenticros/agenticros-skill-followme/issues"},"license":"Apache-2.0","readme":"# agenticros-skill-followme\n\nFollow Me skill for [AgenticROS](https://github.com/your-org/agenticros): the robot follows the user using depth (and optionally Ollama/VLM) and publishes `cmd_vel`.\n\n## What it does\n\n- **Behavior**: A control loop runs at a configured rate (e.g. 5 Hz). It samples distance from a **depth topic** (e.g. RealSense) and optionally uses Ollama (e.g. Qwen VL) for person detection and left/right steering. It publishes twist commands to `cmd_vel` to keep the user at a target distance and centered. **You must set `depthTopic`** in `config.skills.followme` (e.g. `/camera/camera/depth/image_rect_raw`) for non-zero motion; otherwise the published twist stays zero. When you **stop** Follow Me, the skill publishes zero twist to `cmd_vel` so the robot actually stops (many bases hold the last command until a new one arrives).\n- **Turn left/right**: With **depth only**, the skill uses left/center/right sectors of the depth image to turn toward the person (closest sector). With **Ollama** enabled, the VLM provides left/center/right for steering.\n- **Find person when lost**: When no valid depth is received (person left the view), the robot **rotates in place** (search mode), alternating direction every few seconds so it can find the person again.\n- **Back up when too close**: If the person is closer than ~80% of the target distance, the robot drives backward.\n- **No separate service**: Control is entirely via the plugin and the `follow_robot` tool in chat (Zenoh/ROS2). There is no HTTP follow-robot service or port.\n- **Tools**:  \n  - **`follow_robot`** — Start, stop, or query Follow Me (actions: `start`, `stop`, `status`).  \n  - **`follow_me_see`** — When Ollama is enabled, returns what the vision model sees (person position/distance hint).  \n  - **`ollama_status`** — Checks if Ollama is reachable and lists models (for debugging/setup).\n- **Config**: All options live under **`config.skills.followme`** (see [Contract](#contract-summary) and [Install](#install-and-run)).\n\n## Install and run\n\n1. **Install the skill** where the OpenClaw gateway can load it:\n   - **Option A (recommended)**: Add to AgenticROS config as a package name:\n     - In OpenClaw config, under `plugins.entries.agenticros.config`, set:\n       - `skillPackages`: `[\"agenticros-skill-followme\"]`\n     - Install the package in the same environment as the gateway (e.g. `pnpm add agenticros-skill-followme` in the gateway app, or install globally).\n   - **Option B**: Clone this repo into a directory and add that directory to `skillPaths`:\n     - `skillPaths`: `[\"/path/to/agenticros-skill-followme\"]`\n     - Run `pnpm install` and `pnpm build` in this repo.\n2. **Configure** the skill in the same config under `skills.followme` (see [Contract](#contract-summary)).\n3. **Restart the OpenClaw gateway** so the plugin loads the skill.\n4. In chat, use natural language: e.g. “follow me”, “start following”, “stop following”. The agent will call `follow_robot` with the appropriate action.\n\n## Project structure\n\n| Path | Purpose |\n|------|--------|\n| `src/index.ts` | Entry point; exports `registerSkill(api, config, context)`. |\n| `src/config.ts` | Follow Me config slice: reads `config.skills.followme` and applies defaults. |\n| `src/loop.ts` | Control loop: depth + optional Ollama, publishes `cmd_vel`; start/stop/status. |\n| `src/tools/follow-robot.ts` | Registers `follow_robot` (start/stop/status). |\n| `src/tools/follow-me-detection.ts` | Registers `follow_me_see` (what the tracker sees when useOllama is on). |\n| `src/tools/ollama-status.ts` | Registers `ollama_status`. |\n\nThe skill gets **transport** and **depth** from the plugin via **context**:\n\n- `context.getTransport()` — ROS2 transport (subscribe/publish).\n- `context.getDepthDistance(transport, topic, timeoutMs?)` — Sample depth topic and return median distance (meters).\n- `context.logger` — Plugin logger.\n\nConfig is the full AgenticROS config; the skill only uses `config.skills.followme` and, for topic resolution, `config.robot.namespace` / `config.teleop.cmdVelTopic` where needed.\n\n## Using this repo as a template for a new skill\n\n1. **Copy or fork** this repo and rename the package (e.g. `agenticros-skill-myskill`).\n2. **`package.json`**:  \n   - Set `\"agenticrosSkill\": true`.  \n   - Set `\"main\"` to your built entry (e.g. `\"dist/index.js\"`).  \n   - Keep `peerDependencies` on `@agenticros/agenticros` and add any deps your skill needs (e.g. no extra deps for Ollama — this skill uses `fetch`).\n3. **Entry point**: Export a single function **`registerSkill(api, config, context)`** that:\n   - Reads its config from `config.skills.<skillId>` (e.g. `config.skills.followme`).\n   - Registers tools with `api.registerTool(...)` (and optionally commands, etc.).\n   - Optionally starts a background loop (as here) using `context.getTransport()` and `context.getDepthDistance(...)`.\n4. **Config slice**: Validate and default your slice (e.g. with a small helper like `getFollowMeConfig` in `src/config.ts`).\n5. **Build**: Run `pnpm build` (or `npm run build`) so the plugin can load your `main` entry.\n6. **Install**: Users add your package to `skillPackages` or install into a path in `skillPaths` and set `config.skills.<skillId>` as needed.\n\nFull contract and types: **[AgenticROS docs: Skills](https://github.com/your-org/agenticros/blob/main/docs/skills.md)** (replace with your repo URL).\n\n## Config options (config.skills.followme)\n\n| Option | Description |\n|--------|-------------|\n| `depthTopic` | **Required for motion.** Depth image topic (e.g. `/camera/camera/depth/image_rect_raw`). If empty, twist stays 0. |\n| `targetDistance` | Target follow distance in meters (default 1.0). |\n| `rateHz` | Loop rate (default 5). |\n| `minLinearVelocity` | Min forward/back speed when adjusting distance (default 0.3). |\n| `cmdVelTopic` | Override cmd_vel topic (default: from teleop or robot namespace). |\n| `useDepthSectors` | If true (default), use depth left/center/right sectors to turn toward the person when not using Ollama. |\n| `searchAngularVelocity` | Angular speed (rad/s) when rotating to search for person when lost (default 0.4). |\n| `searchTicksBeforeSwitch` | Ticks to rotate one direction before switching when searching (default 15). |\n| `useOllama` | If true, use Ollama for left/right steering (optional). |\n| `cameraTopic`, `ollamaUrl`, `vlmModel` | Used when `useOllama` is true. |\n\n## Contract summary\n\n- **Package**: `package.json` has `\"agenticrosSkill\": true` and a `main` entry that exports **`registerSkill(api, config, context)`**.\n- **Config**: Skill-specific options live under **`config.skills.<skillId>`** (e.g. `config.skills.followme`). The skill validates and defaults its own slice.\n- **Context**: Use **`context.getTransport()`** for ROS2, **`context.getDepthDistance(transport, topic, timeoutMs?)`** for depth (optional), and **`context.logger`** for logging.\n- **Registration**: Call **`api.registerTool(...)`** (and optionally commands) inside `registerSkill`. Do not depend on the plugin’s internal file layout; depend only on the public skill API and types exported by `@agenticros/agenticros`.\n\nFor the full contract and how to create a third-party skill, see **[docs/skills.md](https://github.com/your-org/agenticros/blob/main/docs/skills.md)** in the AgenticROS repo.\n","readmeFilename":"README.md","_rev":"1-e171a201a0b33cd11cbabd8c1b3c3ea2"}