Open-source, local-first social media research agent for Instagram, TikTok, and LinkedIn. Jev routes read-only steps; socai CLI captures cited browser evidence.
AGENTS.md
This repository contains Jev Social, a local Node.js application that lets Jev
choose bounded social-research operations and delegates browser execution to the
installed socai CLI. It supports read-only Instagram, TikTok, and LinkedIn
research, streams captured evidence to a loopback UI, and produces a
source-linked report.
These instructions apply to the entire repository.
Setup
Use Node.js 24, matching .nvmrc. Node.js 22 is the oldest supported runtime,
and CI covers both supported LTS lines.
nvm use
npm ci
Offline development and tests do not need credentials. A live run additionally
needs either an OpenRouter key that can access Jev or an explicit loopback
TypeSafe-compatible decision endpoint, a compatible socai CLI, and a browser
session that can access the selected platform.
Never commit .env, API keys, browser data, downloaded media, run artifacts,
or personal social-media data.
Commands
npm run check # syntax-check the shipped JavaScript
npm test # run the complete offline test suite
npm run dev # local server with Node watch mode
npm start -- status # inspect local readiness
npm start -- serve --no-open # serve the UI at 127.0.0.1:8766
npm start -- search "goal" --limit 4 # live research; requires local setup
Run both npm run check and npm test before submitting a change. The CI
workflow uses the same commands after npm ci.
Architecture
bin/jev-social.jsis the CLI entry point forserve,status,onboard, andsearch.src/app.jsowns the Jev decision loop, checkpoints, event stream, and final run shape.src/decision-provider.jsselects OpenRouter or an explicit loopback System One endpoint, bounds the network response, and prevents credential forwarding.src/classifier.jsbuilds platform choices and validates typed decision responses independently of the selected provider.src/actions.jsbuilds the current finite action space from the goal, installed CLI capabilities, observed targets, and action history.src/socai.jsprobes the installed CLI, maps selected actions to arguments, runs the process, and normalizes progress and errors.src/evidence.jsextracts, deduplicates, sanitizes, and reports captured evidence. Treat CLI and platform output as untrusted input.src/runs.jspersists recoverable checkpoints below the isolated Jev Social state directory.src/server.jsexposes the loopback HTTP/SSE surface and verified media previews. Do not broaden its network binding without explicit design review.public/is the local interactive UI.site/is the separate static project landing page deployed by GitHub Pages.skills/jev-social/is the distributable Agent Skill. Its runtime pin and safety boundary must stay aligned with the documented release.test/mirrors observable server, CLI, decision, evidence, and UI behavior.
Non-negotiable boundaries
- Keep the product read-only. Do not add posting, liking, following, messaging, or other account-changing operations.
- Jev may select only from concrete choices built by the application. Never let a model generate shell commands, selectors, coordinates, arbitrary URLs, or executable browser instructions.
- Browser work stays inside
socai CLI. Detect installed capabilities before a model call and fail visibly when a requested platform or operation is absent. - Accept action targets only from captured results or explicit user URLs, and retain the platform-specific HTTPS allowlist checks.
- Download TikTok media only when the user's goal explicitly requests media download. Reading a video, caption, comments, or metadata is not consent to download the file.
- Preserve recoverable partial results for interruption, login/challenge gates, decision failure, CLI failure, and step limits. Never substitute mock success.
- Keep credentials, environment values, executable paths, run directories, local artifact paths, raw command arrays, and raw run JSON out of user-facing output.
- Treat search cards and opened detail records differently. Do not imply that a post or comment thread was read when only a search result was captured.
- Keep all product UI, documentation, issue, and pull-request text in English.
Output contracts
The CLI sends human-readable progress to stderr and the final run object to stdout. Preserve the meaning of these fields when changing the run loop:
statusandstopReasondescribe completion or the exact partial outcome;result.itemscontains sanitized evidence with validated source URLs;actionsrecords what Jev selected and what was actually executed;reportandfinalSocaiOutputcontain the readable evidence synthesis;elapsedMs,jevElapsedMs, andsocaiElapsedMsremain separate timings.
The browser UI consumes streamed events before the final object arrives. Evidence cards must remain visible while the report streams, and raw diagnostic payloads must not replace the human-readable state.
Testing guidance
- Automated tests must remain offline: no real social accounts, browser
sessions, OpenRouter calls, paid model calls, or live
socaicommands. - Inject clients, environment objects, process runners, clocks, and temporary state directories rather than depending on a developer machine.
- Add focused tests for every observable behavior change. Prefer the matching
file in
test/; use DOM fixtures for browser code and temporary directories for persistence or media tests. - Test failure and partial-result paths as well as the successful path, especially aborts, malformed Jev responses, missing capabilities, unsafe URLs, login gates, empty evidence, and media validation.
- Do not weaken sanitization, source validation, or an existing assertion to make a test pass.
Release and documentation consistency
Public no-clone commands are pinned to the current release. When changing the
package version or released runtime, update the package metadata, README, static
site, site/llms.txt, Agent Skill, and distribution tests together. Do not add
automatic-consent flags to package-runner commands.
Keep pull requests focused. Document live browser validation separately from offline test evidence, and open an issue first for substantial behavior or UI changes.