Project OS Organizer

Privacy-first, chat-first project manager for vibe coders. Track projects, capture updates, and resume work across local folders, Claude/Codex, and GitHub wi...

Security Scan

The skill's files, env requirements, and instructions are consistent with a local-first project manager that only indexes chats/GitHub or clones remote code when you explicitly opt in.

Purpose & Capability

Name/description (local-first, chat-first project manager) aligns with requested binaries and env vars: only python3 is required and the optional env flags control chat indexing, GitHub sync, home discovery, and remote install. The scripts are wrappers that expect a separate project-os repo (project_os package) and will refuse or require explicit opt-in before performing remote clone/install.

Instruction Scope

SKILL.md directs the agent to run scripts/project_router.sh which in turn runs bootstrap/setup scripts and the project_os Python CLI. Those scripts will scan local roots and (if enabled) conversation roots and GitHub. By default chat indexing, home-discovery, GitHub sync, and remote install are disabled; enabling them is controlled by explicit environment variables (PROJECT_OS_INCLUDE_CHAT_ROOTS, PROJECT_OS_ENABLE_GITHUB_SYNC, PROJECT_OS_ENABLE_HOME_DISCOVERY, PROJECT_OS_AUTO_SETUP and PROJECT_OS_ALLOW_REMOTE_INSTALL).

Install Mechanism

No automated install spec in the registry; this is instruction+script based. Remote install is possible only when two opt-in flags are set and the repo URL matches a TRUSTED_REPO_URL; the remote clone uses a GitHub URL. There are no opaque downloads or URL shorteners in the codebase.

Credentials

The skill requests only PROJECT_OS_ROOT (or explicit remote-install opt-in) plus optional flags for chat/GitHub/home discovery. If you enable GitHub sync, the tooling will look for GITHUB_TOKEN or call the gh CLI; enabling chat indexing or home discovery allows scanning of local chat folders and user home subfolders. These env/credential needs are proportionate but enable access to potentially sensitive local data when turned on.

Persistence & Privilege

always is false and the skill does not request system-wide privileges. It creates data under $HOME/.project_os and may start a local dashboard (binds to PROJECT_OS_HOST:PROJECT_OS_PORT, default 127.0.0.1:8765). Daemonization is handled locally via daemonize_command.py. Nothing modifies other skills or global agent settings.

Assessment

This skill is coherent with its stated purpose, but it can access or index local chat transcripts, home directories, and GitHub only when you explicitly enable those options. Before installing or running: 1) Keep remote-install disabled unless you trust the repository and set PROJECT_OS_ROOT to a local checkout. 2) Only set PROJECT_OS_INCLUDE_CHAT_ROOTS=1 or PROJECT_OS_ENABLE_GITHUB_SYNC=1 if you want those features and understand they will read local chat folders or use your GITHUB_TOKEN / gh CLI. 3) Expect files under ~/.project_os and a local web dashboard at 127.0.0.1:8765 when started. 4) Review the upstream project-os repository (PROJECT_OS_REPO_URL / PROJECT_OS_TRUSTED_REPO_URL) before enabling auto-install. If you want a minimal footprint, leave all optional env flags unset and point PROJECT_OS_ROOT to a vetted local copy.

Project OS Organizer Skill

Why This Skill

Use this when a user is juggling many AI-built projects and needs one simple command surface to:

1. See what is active now.
2. Capture progress and next steps fast.
3. Resume any project in one jump (local/GitHub/chat).

Security Defaults

1. Remote install is disabled by default.
2. Chat transcript indexing is disabled by default.
3. GitHub sync/token usage is disabled by default.
4. Home-directory heuristic discovery is disabled by default.

To opt in explicitly:

1. PROJECT_OS_INCLUDE_CHAT_ROOTS=1 enables chat transcript indexing.
2. PROJECT_OS_ENABLE_GITHUB_SYNC=1 enables GitHub username/token integration.
3. PROJECT_OS_ENABLE_HOME_DISCOVERY=1 enables broad home-directory discovery.
4. PROJECT_OS_AUTO_SETUP=1 PROJECT_OS_ALLOW_REMOTE_INSTALL=1 allows remote clone/install if PROJECT_OS_ROOT is missing.

Goal

Produce a complete, local-first project inventory that answers:

1. What projects exist right now?
2. Which are active/blocked/stale?
3. What is each project actually about?
4. Where did the user leave off?
5. How can the user jump back in immediately?
6. How can the user quickly edit status/next steps/items without leaving OpenClaw?

Default Behavior (Natural Language First)

Default action for every user message:

1. Interpret the message.
2. Run: scripts/project_router.sh "<user message>".
3. Return the router output directly in plain language.

Users should not need to type scripts, Python, paths, or flags.

Fallback for power users:

• Use the short wrapper command: project ...
• Examples: project, project focus, project today, project inbox "idea: test", project dashboard start

Plain-language request mapping:

1. "What am I working on today?" -> activity today
2. "Show my projects" -> grouped project list (Now/Later/Blocked/Done)
3. "Focus list" -> top focus items
4. "Add this idea: ..." -> inbox capture
5. "Next for project-os: ..." -> add next
6. "Mark X blocked" -> set simple status
7. "Start dashboard" -> dashboard start
8. "Resume project X" -> resume pack
9. "Only track A, B, C" -> set tracked scope (activity will only include these)
10. "Mute X" / "Untrack X" / "Show scope" -> scope controls

Response style in non-technical mode:

1. Keep responses short and direct.
2. Do not expose technical command details unless user asks.
3. For activity questions, always return Activity Criteria + day sections.
4. If a project name is ambiguous, ask one short clarification question.

Project Definition

Treat an item as a project if it matches any of these:

1. Git repository folder.
2. Non-git code folder with project markers (package.json, pyproject.toml, Cargo.toml, etc).
3. Chat session (Claude/Codex) that does not match an existing project; create a chat-derived project.
4. Claude workspace chats should map to deeper subprojects when session folders indicate a nested workspace path.

Reject likely non-project folders in collection roots (docs-only, logs, backups, notes-only folders) unless there is strong code/marker evidence. Reject low-signal chat-only entries as standalone projects unless they contain a useful path hint or meaningful project intent.

Required Workflow

1. Run scripts/bootstrap.sh first.
2. Validate coverage:
   • run python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-projects --limit 200
   • run python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-sessions --limit 50
   • run python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json list-items --status open --limit 80
   • run python3 -m project_os.cli --db ~/.project_os/openclaw_test.db --config ~/.project_os/openclaw_test_config.json squash-chat-projects
3. If user wants visual mode, run scripts/start_dashboard.sh.
4. If user wants quick resume context, run scripts/write_memory.sh and use ~/.project_os/PROJECT_MEMORY.md.

First-Run (Production)

Run this for a first-time user:

1. scripts/openclaw_smoke_agent.sh
2. scripts/read_smoke_result.sh
3. Confirm:
   • RESULT_STATUS=ok
   • RESULT_DASHBOARD_URL=...
   • RESULT_PORT_8765_LISTENING=yes

If project-os repo is not present locally, the skill will fail safely by default and instruct setting PROJECT_OS_ROOT. Remote install is explicit opt-in only.

Operation Modes

• Dashboard mode: simple visual triage (Focus Today, Now, Blocked, Later, Done) and jump links.
• Dashboard mode includes:
  • Quick Inbox capture (freeform note -> auto-routed update/next/reminder/idea/blocker)
  • Daily Check-In panel (done + next + blocker)
  • Focus list, stale nudges, weekly snapshot, and server health
• Dashboard intentionally avoids recommendation-score noise and focuses on plain language:
  • What it is (derived from project files like README/package metadata)
  • Where left off
  • Do next
  • inline editing: set simple status (now/later/blocked/done), set next action, add update/next/reminder/idea/blocker, mark items done/dismissed
  • session resume buttons for both tools (Resume in Claude and Resume in Codex) when session link is valid
• Memory mode: markdown snapshot for fast resume in any chat.

Default recommendation: use both.

OpenClaw Command-First Updates

Use CLI commands as the primary interface:

1. add-update for what changed.
2. add-next for the immediate next step (also updates project next_action).
3. add-reminder for date/time-based follow-ups.
4. add-idea for backlog thoughts.
5. list-items and set-item-status to triage/close items.
6. Use scripts/project_actions.sh for short aliases around these commands.
7. For activity-window questions ("what did I work on today/yesterday"), run scripts/activity_report.sh --when both or scripts/project_actions.sh activity --when both.
8. Do not guess activity by project name or status; only use timestamp evidence from the report criteria.
9. Activity report excludes archived projects by default (use --include-archived only if user asks).
10. Response contract for activity-window answers:

• always include Activity Criteria
• always include Today (...) and/or Yesterday (...) headings
• include at least one evidence line per listed project (local_commit, github_push, session, or note)
• if no projects match, explicitly return - none

OpenClaw Usage

1. In OpenClaw, invoke this skill by name: project-os-organizer.
2. For first run setup: project setup (or scripts/easy_mode.sh setup).
3. Default day-to-day: just type plain English in chat and route through project_router.sh.
4. Optional shortcuts use only project ....
5. For one-command local install from this repo, run scripts/install_openclaw_skill.sh.
6. For non-interactive OpenClaw agents, use:
   • scripts/openclaw_smoke.sh for strict CI-style smoke (non-zero exit on failure)
   • scripts/openclaw_smoke_agent.sh for agent-safe smoke (always exits zero, returns RESULT_STATUS)
   • scripts/read_smoke_result.sh to fetch the last smoke result file when command output is flaky
   • scripts/bootstrap.sh --noninteractive (timeout-safe quick mode)
   • scripts/bootstrap.sh --noninteractive-full (full refresh mode)
   • scripts/start_dashboard.sh --detach --restart
   • Smoke commands return machine-readable lines:
     • RESULT_STATUS
     • RESULT_ERROR
     • RESULT_DASHBOARD_URL
     • RESULT_DASHBOARD_PID
     • RESULT_PORT_8765_LISTENING
     • RESULT_CURL_HEAD
     • RESULT_SMOKE_LOG
     • RESULT_DASHBOARD_LOG
     • RESULT_RESULT_FILE
7. For quick editing from chat:
   • scripts/project_actions.sh list --limit 80
   • scripts/project_actions.sh set-status --project "<name|id>" --status blocked
   • scripts/project_actions.sh set-next --project "<name|id>" --text "next step"
   • scripts/project_actions.sh add-update --project "<name|id>" --text "what changed"
   • scripts/project_actions.sh add-next --project "<name|id>" --text "immediate next step"
   • scripts/project_actions.sh add-reminder --project "<name|id>" --text "follow up" --due 2026-03-01
   • scripts/project_actions.sh add-blocker --project "<name|id>" --text "what is blocked"
   • scripts/project_actions.sh simple-status --project "<name|id>" --status now
   • scripts/project_actions.sh focus --limit 3
   • scripts/project_actions.sh stale --days 14 --limit 20
   • scripts/project_actions.sh weekly --days 7 --limit 12
   • scripts/project_actions.sh notify --period daily
   • scripts/project_actions.sh inbox --text "freeform note"
   • scripts/project_actions.sh checkin --project "<name|id>" --done "..." --next "..." --blocker "..."
   • scripts/project_actions.sh duplicates --limit 50
   • scripts/project_actions.sh merge --keep "<id|name>" --drop "<id|name>"
   • scripts/project_actions.sh ask --text "mark project-os blocked"
   • scripts/project_actions.sh set-item --item <id> --status done
8. For "worked on today/yesterday":
   • scripts/project_actions.sh activity --when both
9. For personal scope control:
   • scripts/project_actions.sh scope --set "project-os" "polymarket-trader-v2"
   • scripts/project_actions.sh track --project "project-os"
   • scripts/project_actions.sh mute --project "clawd"
   • scripts/project_actions.sh scope
   • Add --include-archived only on explicit request.
   • Return the output sections Activity Criteria, Today (...), and Yesterday (...) so the user sees exactly how projects were counted.

Safety and Scope

1. Local-first only.
2. Do not mutate repositories/servers automatically.
3. Do not invent project state; infer from scans/sessions and expose uncertainty.
4. Prefer broad root coverage to avoid missing nested subfolders.
5. Keep non-git project discovery at root-level by default (include_nested_non_git_projects: false) to avoid noisy submodules.
6. Keep collection discovery strict: include real project subfolders, drop random text-only folders.

References

• references/project-definition.md
• references/workflow.md