claude-world-studio
CLAUDE.md71 starsChanged 25 days agoMITView on GitHub
Content pipeline app: trend discovery, deep research, social publishing — with agentic memory, goals, and strategy (v2.3).
- Reads credentials
In this repository4 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- content-pipelineSkill
- studioSkill
- threads-viral-agentSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
Quality gate consistency: every publish entry point (REST /api/publish, /batch, MCP tool, scheduler) must enforce settings.minOverallScore …
- Very specific: line 46
Test isolation: set STUDIO_USER_DATA_PATH to a mkdtemp dir before dynamically importing any DB-touching module (static imports hoist above …
- Very specific: line 79
Verify the artifact, not the config: spctl --assess --type execute on the .app must say accepted / Notarized Developer ID, and xcrun …
- Distinctive: line 100
Credentials from DB: All tokens and API keys are stored in SQLite DB and loaded automatically by Studio MCP tools.
- Distinctive: line 102
Timeout safety: All MCP tool calls have timeouts to prevent hanging sessions.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Claude World Studio
Content pipeline app: trend discovery, deep research, social publishing — with agentic memory, goals, and strategy (v2.3).
Architecture
server/— Express + WebSocket server, Claude Agent SDK integrationserver/services/— Scheduler, social publisher, Studio MCP toolsserver/services/memory-service.ts— Long-term memory store (SQLite FTS5); singletonmemoryServiceserver/services/agent-orchestrator.ts— Goal state machine (PLAN→EXECUTE→REFLECT→COMPLETE); singletonorchestratorserver/services/strategy-agent.ts— Analytics-driven content strategy; singletonstrategyAgentserver/routes/agent.ts— REST API for goals, memories, reflections, workflows, matrix-runserver/cleanup-registry.ts— Centralized cleanup (pattern from Claude Code)client/— React 19 + Tailwind UI (Vite build)client/components/AgentDashboard.tsx— Goals/Workflows/Memory/Strategy dashboard pageclient/hooks/—useApi(typed fetch),useLanguage(context)electron/— Electron desktop wrapperserver-dist/— Build output: the packaged server bundle (git-ignored, see Desktop packaging)scripts/— Build/test tooling (build-server.cjs,electron-build.cjs,desktop-smoke.cjs,ensure-native-abi.cjs) plus dev-onlythreads_api.py; nothing here runs at server runtime.claude/skills/— Skill definitions for Claude Code
Agentic Subsystem (v2.2)
DB Tables
| Table | Purpose |
agent_goals | Persistent goal tracking — status, progress, sub-tasks JSON |
agent_memories | Long-term knowledge store — FTS5 indexed, type-tagged |
agent_memories_fts | FTS5 virtual table — kept in sync via DB triggers |
agent_reflections | Per-session self-evaluation records |
agent_workflows | Reusable prompt template library |
Key Patterns
searchMemoriesStmtCache(db.ts) — bounded Map (max 8 SQL variants) caches dynamic FTS5 statementsevictionScheduledflag (OrchestratorGoalRun) — prevents duplicate 10-min eviction timers- Yield-point guard in
executeStateMachine— checksrun.stateafter everyawaitso abort/pause isn't overridden markStaleGoalsFailed()on orchestrator startup — reconciles orphaned active goals from previous server runsgetMemoriesByType()store method — DB-levelWHERE memory_type = ?filter; never fetch-then-filter in JS- NULL-binding trap:
WHERE (account_id = ? OR account_id IS NULL)with a NULL bind collapses to global-only rows. When a filter param isundefined, use a dedicated no-filter statement (seegetContextMemoriesAllAccounts,getMemoriesByType) - One-time migrations: guard with a settings-table flag (e.g.
migration_publish_score_backfill) — never write data backfills that re-run on every boot - Quality gate consistency: every publish entry point (REST
/api/publish,/batch, MCP tool, scheduler) must enforcesettings.minOverallScore(70 fallback); scheduled tasks additionally raise the gate tomax(setting, task.min_score)viacreateStudioMcpServer({minScore}). Gates raise, never lower - Never ship the
datadirectory or.envvia electron-builderfiles/extraResources— the live dev DB holds real tokens; this leaked credentials in v1.3.0–v2.0.0 releases scripts/ensure-native-abi.cjs(pre dev/test/start + postinstall) — auto-rebuilds better-sqlite3 whenelectron:buildleaves an Electron-ABI binary behind- Test isolation: set
STUDIO_USER_DATA_PATHto a mkdtemp dir before dynamically importing any DB-touching module (static imports hoist above the env assignment) - Agent SDK 0.3:
query()options are typed with the SDK'sOptions; the SDK spawns its bundled native Claude Code binary (noexecutable/Node path needed, even under Electron). Its peers@anthropic-ai/sdkand@modelcontextprotocol/sdkare declared as direct dependencies. Models use theopus/sonnetaliases so they track the current Claude family
Known Limitations
- Goal pause/resume/abort works only for runs launched via
orchestrator.runGoal(matrix-run); goals created byPOST /api/agent/goalsor thecreate_goal_sessionMCP tool return 409 (no in-memory run) and terminate viamarkStaleGoalsFailedon restart agent_memories_ftsis external-content FTS5 keyed on the implicit rowid of a TEXT-PK table — runningVACUUMmay renumber rowids and desync the index. No code runs VACUUM; don't add one without rebuilding the FTS index afterwards
MCP Tools (all 8)
| Tool | Purpose |
publish_to_threads | Publish post (quality gate enforced) |
get_publish_history | Fetch recent publish records |
upload_image | Upload workspace image (path traversal protected) |
create_goal_session | Create agent_goals record |
run_reflection_loop | Save reflection → improvement memory |
search_memory | FTS5 search with goalId/accountId/type filters |
generate_strategy_from_analytics | Inline analytics strategy (number[] hours) |
run_strategy_agent | Full StrategyAgent pipeline with calendar |
Security Scanning (CodeQL)
Code scanning is at 0 open alerts. Two rules were triaged on 2026-10-22; the reasons live on the alerts themselves, summarised here so nobody re-derives them:
js/path-injection—server/routes/files.ts, dismissed false positive. The file route checks containment twice:resolveWorkspaceFilePath()lexically, before any filesystem call, and arealpath()comparison after it, to catch a symlink inside the workspace pointing out. CodeQL does not model the helper as a barrier, so it still flags therealpath()call.test/files-path-traversal.test.tsrefuses 12 traversal variants and keeps 5 positive controls — run it whenever that route changesjs/missing-rate-limiting×8 — dismissed.server/middleware/rate-limiter.tsis hand-rolled (120 req/60 s per IP, covered bytest/rate-limiter.test.ts) and CodeQL only models a fixed set of limiter libraries, so it flags routes that already sit behindapp.use(rateLimiter)— those are false positives. The twoapp.get("/")handlers inserver.tsgenuinely do precede the limiter, deliberately, so page assets don't consume the API budget; they serve one staticindex.html, so those are "won't fix"- Both dismissals rest on the server binding
127.0.0.1only (verified withlsof: a singleTCP 127.0.0.1:<port>socket, no wildcard, and a refused connect to the host's LAN address). If that ever changes, revisit both. - Editing a flagged line re-fingerprints its alert: CI goes red with a "new" alert that is the same finding. Re-dismiss with the same reason — don't reshape working code to satisfy the scanner
Releasing a Desktop Build
- Staple the DMG, then recompute
latest-mac.yml.xcrun stapler staplerewrites the DMG, so the sha512 and size electron-builder wrote before stapling no longer match. The manifest is not re-checked at build time and nothing fails locally — the breakage lands later, on users whose installed app tries to auto-update. Recompute the hash from the stapled file and diff it against the manifest before uploading. This has cost time twice (v2.3.0, then again at v2.4.0 planning) - Verify the artifact, not the config:
spctl --assess --type executeon the.appmust sayaccepted / Notarized Developer ID, andxcrun stapler validatemust pass on both the.appand the.dmg - Content-audit the built artifact before upload.
app.asar.unpackedmust contain exactly.claude/,dist/,node_modules/,package.json,server-dist/— nodata/, no*.db, no.env, no keys. Releases v1.3.0–v2.0.0 shipped a live SQLite DB with real tokens; thefilesallow-list is what prevents a repeat, so check the output rather than trusting it - Build from a clean checkout.
dist/is both the vite output and electron-builder's output directory, so a stale local tree can mix artifacts - Release assets use the dashed
safeArtifactName(Claude-World-Studio-<version>-arm64.dmg), andlatest-mac.ymlmust be uploaded with them or auto-update breaks
Desktop Packaging
The packaged app runs one esbuild bundle, not the TypeScript sources. scripts/build-server.cjs compiles server/server.ts → server-dist/server.mjs; electron/server-runtime.cjs spawns that with Electron-as-node. Rules that keep it working:
- Only
runtime-paths.tsmay readimport.meta.url. Bundling collapses every module'simport.meta.urlonto the bundle's path, so a per-file__dirnamesilently resolves to the wrong depth. UsegetProjectRoot()instead. The bundle must stay exactly one directory below the app root for that to hold —test/packaging.test.tsasserts it EXTERNALinscripts/build-server.cjsis load-bearing.better-sqlite3is a native addon;@anthropic-ai/claude-agent-sdklocates its CLI binary withcreateRequire(import.meta.url).resolve(), so it only works from a real package directory;zodmust be a single instance shared with the SDK, whosetool()helper converts schemas with its own copybuild.filescan only exclude undernode_modules. electron-builder'sgetNodeModuleFileMatcherkeeps just the!patterns and prepends**/*, so a re-include after!node_modules/**/*is silently dropped — write a deny-list, never an allow-list, for dependencies- esbuild's ESM output has no
require.scripts/build-server.cjsprepends acreateRequirebanner; without it, esbuild's__requireshim throws the first time bundled CommonJS reaches a dynamic require test/packaging.test.tsrecomputes the runtime dependency closure and fails if an exclusion covers something the app resolves on disk — or if a new dependency ships without being needednpm run test:desktop-smokechecks the shipped tree (bundle unpacked,tsx/esbuild/@anthropic-ai/sdkabsent, better-sqlite3 addon present, Agent SDK loads) before exercising the running app- The npm package is separate and still ships
server/+ runstsx server/server.ts;tsxstays a production dependency for it
Key Design Rules
- No Python runtime dependencies: Publishing uses native TypeScript
fetch(), not Python scripts. Thethreads_api.pyis a dev-only tool, not used by the server. - Workspace containment: The AI agent operates within the session workspace only. Never reference
~/Downloadsor paths outside workspace in prompts or examples. Use relative paths likedownloads/card.pdf. - Credentials from DB: All tokens and API keys are stored in SQLite DB and loaded automatically by Studio MCP tools. Never search the filesystem for credentials.
- MCP-first publishing: Publishing goes through the
publish_to_threadsStudio MCP tool, which reads tokens from DB. No direct API calls from the agent. The system prompt's embedded SKILL.md is for content strategy only — all execution uses MCP tools. - Timeout safety: All MCP tool calls have timeouts to prevent hanging sessions.
- Programmatic quality gates: The
publish_to_threadsMCP tool enforcesscore >= minOverallScorefrom settings. The agent cannot bypass this via prompt manipulation. - Cleanup registry: Modules register cleanup functions via
registerCleanup(). Shutdown runs all cleanups in parallel. Sessions auto-register on creation and unregister on close. - Typed SDK output: Agent output stream uses
SDKOutputMessagediscriminated union (notany). Defined inserver/cli-session.ts. - Error diagnostics: Logger keeps a 100-entry ring buffer.
GET /api/diagnostics/errorsexposes it. Client ErrorBoundary reports toPOST /api/diagnostics/errors.
Dev Commands
npm run dev # Start dev server + Vite
npm run build # Build client
npm run typecheck # TypeScript check
npm run build:server # Bundle server/ → server-dist/server.mjs (esbuild)
npm run electron:dev # Electron dev mode
npm run electron:build # Production .dmg (build + build:server + package)Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

