SharkFin v1.0.7

Local-first AI agent automation for power users. SharkFin runs on your machine, executes real workflows with transparent logs, and ships with playbooks, Forge self-improvement, Ghostwriter brand drafting, multi-agent orchestration, and optional Nvidia NemoClaw guardrails.

Why SharkFin

• Published npm package for fast customer setup
• Playbooks for repeatable local automations
• Forge for self-improvement and playbook generation
• Ghostwriter for local-first brand drafting and optional SharkBook publishing
• Multi-agent workflows for practical research, writing, and file-producing pipelines
• Transparency logs and dry-run support
• Optional NemoClaw security controls

Quick Start

npm_config_prefix="$HOME/.local" npm install -g sharkfin
export PATH="$HOME/.local/bin:$PATH"
sharkfin register
sharkfin start

If npm install -g sharkfin fails with an EACCES permission error on Linux because npm is trying to write to a system path like /usr/lib/node_modules, use the user-local prefix install above.

If you prefer the standard global npm path and your machine allows it:

npm install -g sharkfin
sharkfin register
sharkfin start

If you want to work from source instead of the published npm package:

git clone https://github.com/sharkfinAI/sharkfinApp.git
cd sharkfin
npm install
npm run build
npm link
sharkfin register
sharkfin start

Command Reference

sharkfin start
sharkfin register
sharkfin logs

sharkfin agents launch <count> [--role <role>]
sharkfin agents list
sharkfin agents stop <id>
sharkfin agents status
sharkfin agents run <goal> [--agents <roles>]

sharkfin playbooks list
sharkfin playbooks simulate <name>
sharkfin playbooks run <name>

sharkfin forge suggest
sharkfin forge suggest --show-prompt
sharkfin forge "<description>"
sharkfin forge "<description>" --simulate
sharkfin forge "<description>" --run

sharkfin ghostwriter start "<brand>"
sharkfin ghostwriter status [id]
sharkfin ghostwriter schedule <id> --run-at <iso>
sharkfin ghostwriter cycle <id> [--count <n>]
sharkfin ghostwriter manage <id> [--publish] [--sync-engagement]
sharkfin ghostwriter run-now <id>
sharkfin ghostwriter publish <id>
sharkfin ghostwriter reply <id> --post <postId>
sharkfin ghostwriter engagement <id>
sharkfin ghostwriter process-due
sharkfin ghostwriter stop <id>
sharkfin ghostwriter social status
sharkfin ghostwriter social enable --api-url <url> [--channel <name>] [--auto-publish]
sharkfin ghostwriter social disable

sharkfin telegram-auth
sharkfin discord-auth

sharkfin security enable nemoclaw
sharkfin security status
sharkfin security disable nemoclaw

Forge in v1.0.7

Forge is the self-improvement and playbook-creation surface in SharkFin today.

Included in v1.0.7:

• sharkfin forge suggest reviews recent action logs and proposes playbook or workflow improvements
• sharkfin forge suggest --show-prompt shows both the detected patterns and the exact prompt used to generate suggestions
• sharkfin forge "<description>" creates a playbook from plain English and validates it with a dry-run before saving
• sharkfin forge "<description>" --simulate makes that validation step explicit
• sharkfin forge "<description>" --run validates, saves, and executes the generated playbook
• provider preflight and environment warnings before generation
• proactive self-improvement suggestions while SharkFin is running, when Forge is enabled

Forge Workflow Examples

Review improvement ideas from recent usage:

sharkfin forge suggest
sharkfin forge suggest --show-prompt

Create and validate a playbook before saving:

sharkfin forge "Create a playbook that summarizes recruiter outreach into a local markdown brief"

Create, validate, save, and then execute:

sharkfin forge "Create a playbook that researches founder GTM ideas and writes a concise report" --run

Suggested end-to-end loop:

sharkfin playbooks run morning-inbox
sharkfin playbooks run tiktok-trend-opportunity-brief
sharkfin forge suggest --show-prompt
sharkfin forge "Create a playbook that turns repeated inbox triage into a reusable daily summary flow" --simulate

Ghostwriter in v1.0.7

Ghostwriter in v1.0.7 is a local-first brand drafting and scheduling workflow with optional SharkBook publishing.

Included in v1.0.7:

• workspace-based brand setup with topics, audience, voice, cadence, and local state
• immediate local draft generation with deterministic fallback when the model is unavailable
• scheduled drafts and recurring content cycles
• ghostwriter manage brand loop for one workspace: fresh drafts, due work, optional publish, optional engagement sync
• markdown output that includes platform variants for: LinkedIn, X, and YouTube Community
• best-effort trend research that enriches draft prompts without blocking generation
• optional SharkBook publishing, reply publishing, and engagement sync over HTTP API

Not included in v1.0.7:

• direct LinkedIn, X, or YouTube publishing
• image generation
• autonomous multi-platform comment ingestion

Ghostwriter Workflow Examples

Create a workspace and generate a draft:

sharkfin ghostwriter start "FounderBrand" --topics "local ai, automation" --cadence daily
sharkfin ghostwriter run-now FounderBrand --brief "Draft a short founder update about practical AI workflows"
sharkfin ghostwriter status FounderBrand

Run a cycle or the full brand loop:

sharkfin ghostwriter cycle FounderBrand --count 3
sharkfin ghostwriter manage FounderBrand --count 2

Enable SharkBook and use the managed workflow:

sharkfin ghostwriter social enable --api-url http://localhost:3002 --channel general --auto-publish
sharkfin ghostwriter manage FounderBrand --count 2 --publish --sync-engagement

SharkBook Integration

SharkFin is currently configured to publish Ghostwriter output to SharkBook through the optional HTTP integration.

• enable it with ghostwriter social enable
• publish drafts with ghostwriter publish
• publish replies with ghostwriter reply
• refresh engagement with ghostwriter engagement

This integration is API-based. SharkFin does not need to run inside the sharkfin-social repo, but the SharkBook app must be running and reachable at the configured apiUrl.

Multi-Agent

SharkFin supports multi-agent orchestration for practical workflows such as research, writing, and file-producing runs.

Best fit in v1.0.7:

• concrete goals with one clear final deliverable
• research and writing handoffs
• workflows that save a final brief, draft, or report locally

Use a more explicit goal when possible. Multi-agent runs are strongest today when you tell SharkFin exactly what output to produce.

sharkfin agents launch 2 --role research
sharkfin agents list
sharkfin agents run "Research local AI workflow opportunities and write a founder brief to ~/.sharkfin/playbooks/founder-brief.md" --agents research,writer
sharkfin agents status

NemoClaw Security

SharkFin includes an optional NemoClaw compatibility layer for extra tool guardrails and audit metadata.

sharkfin security enable nemoclaw
sharkfin security status
sharkfin security disable nemoclaw

Chat Adapter Auth

You can add Telegram or Discord after registration:

sharkfin telegram-auth
sharkfin discord-auth

Notes

• See playbookGuide.md for the current built-in playbooks
• See appREADME.md for deeper app details
• Local deployment is the supported runtime for v1.0.7

GitHub: https://github.com/sharkfinAI/sharkfinApp