MyHacks

MyHacks is a local-first personal OS for Codex.

It gives Codex durable local context: memory, tasks, approvals, workflows, and follow-ups in one private filesystem-native runtime.

Codex should not wake up stateless every session. MyHacks keeps human-readable Markdown around your work, including memory files and structured Markdown records for tasks, approvals, follow-ups, panels, and logs.

The public repository contains the product core. Your real memory, logs, user-specific configuration, and local runtime data stay outside version control.

Try the anonymous demo in under three minutes:

myhacks init
myhacks demo seed
myhacks dashboard
myhacks web

Features

• Operational tasks with status, goal, constraints, assumptions, and next actions.
• Markdown memory with review workflows, sensitivity levels, and rebuildable local record files.
• Approval queue for all external actions.
• Persistent follow-ups and audit logs.
• Generic asset tracking for renewals such as domains, subscriptions, licenses, contracts, and warranties.
• Read-only CLI and local browser dashboards.
• Exportable and reusable skills.
• Local Codex harness integration running in dry_run and fail_closed mode.

Requirements

• Python 3.12+
• a Unix-like local environment or macOS
• no business credentials stored in the repository

Installation

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env.local
./scripts/bootstrap-local.sh
myhacks init

Anonymous Demo

Use the demo seed to inspect MyHacks without adding personal data:

myhacks demo seed
myhacks dashboard
myhacks web

The demo creates one synthetic task, one public memory, one draft-only approval, and one follow-up. It is safe to inspect and safe to delete with your local runtime.

See docs/demo.md for expected output and troubleshooting.

Secure Local Configuration

The public repository must not contain personal data. Always use an untracked local overlay:

cp .env.example .env.local

Configure these local paths:

• MYHACKS_STATE_ROOT
• MYHACKS_DATA_DIR
• MYHACKS_MEMORY_DIR
• MYHACKS_LOG_DIR
• MYHACKS_WORKSPACE_DIR
• MYHACKS_RECORDS_DIR for local Markdown records

Recommended example:

MYHACKS_STATE_ROOT=~/.myhacks
MYHACKS_DATA_DIR=~/.myhacks/data
MYHACKS_MEMORY_DIR=~/.myhacks/memory
MYHACKS_LOG_DIR=~/.myhacks/logs
MYHACKS_WORKSPACE_DIR=~/.myhacks/workspace
MYHACKS_RECORDS_DIR=~/.myhacks/records

Do not commit .env.local. The same rule applies to memory/, housing/, workspace/, logs/, the Markdown records, and any file containing personal content.

Public vs Local

MyHacks is designed around a hard boundary:

GitHub repository
  code, tests, docs, config, anonymous examples

Local runtime
  .env.local, Markdown memory, real tasks, logs, workspace, Markdown records

The public core can be published, forked, tested, and reviewed. The local runtime is where user-specific context lives. Do not copy data from the local runtime into pull requests, examples, issues, fixtures, screenshots, or docs.

Markdown-First Storage

MyHacks treats local Markdown files as the inspectable user-owned layer. Memory lives in curated Markdown files. Operational state lives in one Markdown file per record under MYHACKS_RECORDS_DIR. Lightweight service files support that model: generated .json indexes, append-only .jsonl event journals, small .yaml/.toml configs, .schema.json contracts, and export-only .csv/.ics/.json files.

You can rebuild memory record files from Markdown:

myhacks records rebuild-memory
myhacks records validate
myhacks records manifest
myhacks doctor

If the records directory is deleted, myhacks init recreates the structure. Markdown memory remains the file surface you can inspect, edit, diff, and back up with normal filesystem tools. See docs/storage.md and docs/record-format.md for the current storage contract.

The local browser dashboard is a read-only observability layer over this filesystem model. See docs/local-browser-dashboard.md.

Quickstart

myhacks init
myhacks demo seed
myhacks memory add --type preference --area travel --text "I prefer road trips with reliable Wi-Fi."
myhacks task create --title "Prepare temporary apartment request" --area home --goal "Collect options and outreach drafts"
myhacks task plan <task_id>
myhacks task execute <task_id> --dry-run
myhacks approvals list
myhacks dashboard
myhacks web
myhacks codex status

Security Model

Safe mode is enabled by default:

• browser runs in mock or search-plan mode
• Gmail creates drafts and does not send messages
• Calendar creates proposals instead of real events
• Drive uses mock local storage
• Telegram generates mock notifications
• filesystem access is limited to the configured scope
• payments, signatures, and legal commitments are forbidden

Repository Model

The intended structure is:

• public repo: code, tests, documentation, anonymized examples, base configuration
• local instance: user profile, real Markdown memory, real tasks, runtime outputs, local Markdown records, local overrides
• Codex: attached to the local instance, not to published data

Main Structure

• myhacks/: Python implementation
• tests/: automated tests
• config/: versioned policies and defaults
• docs/: architecture, local setup, and integrations
• examples/: anonymous fixtures
• templates/: generic templates
• workflows/: documented workflows
• examples/assets/: anonymous asset tracking fixtures

Included Skills

• housing_search
• asset_reconciliation
• quote_request
• travel_planning
• appointment_booking
• document_request
• complaint_management
• purchase_research
• email_followup
• decision_matrix
• dashboard_digest

Codex Integration

myhacks codex ... binds a local task to a Codex thread. The core keeps tasks, memory, approvals, follow-ups, and audit logs; Codex owns the agent session and workspace changes.

The harness is intentionally conservative in the public release: default behavior is dry_run and fail_closed. Live execution is an integration boundary, not a requirement for trying the open-source core.

See docs/future-openclaw-integration.md and myhacks/integrations/codex_harness/README.md. For the canonical local workflow, see docs/codex-local-workflow.md. For storage details, see docs/storage.md. For core terms, see docs/glossary.md.

Development

ruff check .
pytest
mypy --no-incremental --no-sqlite-cache myhacks
myhacks records validate
myhacks doctor
cd dashboard-web
npm test -- --run
npm run lint
npm run build

To add a skill:

1. Create myhacks/skills/<skill>.py.
2. Extend Skill.
3. Define manifest.
4. Implement plan() and execute().
5. Register the skill in myhacks/skills/__init__.py.
6. Add workflow, templates, and tests.

Contributions

Open issues or pull requests following CONTRIBUTING.md. PRs must not contain personal data, secrets, absolute local paths, or real examples traceable to actual people.

Good first contributions include docs improvements, anonymous fixtures, dashboard hardening, new dry-run skills, and tests for boundary behavior.

For product questions, demo feedback, and early workflow ideas, see docs/feedback.md and the pinned GitHub Discussion.

Post-Publish Operations

See docs/post-publish-checklist.md and RELEASE.md for the GitHub and runtime steps to maintain after publishing.

License

Vedi LICENSE.