{"id":50814796,"url":"https://github.com/hanymamdouh82/operatree","last_synced_at":"2026-06-13T08:33:35.066Z","repository":{"id":359632008,"uuid":"1236935320","full_name":"hanymamdouh82/operatree","owner":"hanymamdouh82","description":"A project operating system built on your filesystem","archived":false,"fork":false,"pushed_at":"2026-06-13T07:04:46.000Z","size":21446,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T08:33:31.162Z","etag":null,"topics":["cli","devops","filesystem-database","flatfile","fuzzy-search","go","golang","project-management","terminal-based","unix-philosophy","yaml","yaml-parser"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hanymamdouh82.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T18:03:32.000Z","updated_at":"2026-06-13T07:04:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hanymamdouh82/operatree","commit_stats":null,"previous_names":["hanymamdouh82/operatree"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hanymamdouh82/operatree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanymamdouh82%2Foperatree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanymamdouh82%2Foperatree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanymamdouh82%2Foperatree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanymamdouh82%2Foperatree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hanymamdouh82","download_url":"https://codeload.github.com/hanymamdouh82/operatree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hanymamdouh82%2Foperatree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34278153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","devops","filesystem-database","flatfile","fuzzy-search","go","golang","project-management","terminal-based","unix-philosophy","yaml","yaml-parser"],"created_at":"2026-06-13T08:33:34.089Z","updated_at":"2026-06-13T08:33:35.054Z","avatar_url":"https://github.com/hanymamdouh82.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OperaTree\n\n\u003e Your project operating system — built on your filesystem.\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/go-1.26+-00ADD8.svg)](https://golang.org)\n[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()\n\nOperaTree is a CLI tool that brings structure, searchability, and intelligence to how you manage projects — using your filesystem and plain YAML as the only storage. No database required. No vendor lock-in. No proprietary formats.\n\nIt works the way your OS already works: files and directories. Everything is human-readable, Git-friendly, and pipes naturally into standard UNIX tools.\n\n**Setup**\n\n![demo](demo/operatree-demo-1-setup.gif)\n\n**Working with Subjects**\n\n![demo](demo/operatree-demo-2-creating.gif)\n\n**Power Features**\n\n![demo](demo/operatree-demo-3-power.gif)\n\n---\n\n## Philosophy\n\nMost project management tools store your data in a database you don't control. When the tool dies, your data is trapped. When you switch tools, you lose history.\n\nOperaTree takes the opposite approach:\n\n- **Filesystem is the source of truth** — your project lives in directories you own\n- **YAML is the metadata layer** — plain text, readable without any tool\n- **The CLI is just an interface** — your data outlives any software\n\n```\nyour-project/\n├── 00_ADMIN/               # governance, contacts, templates\n├── 01_EVENTS/              # visits, workshops, meetings\n├── 02_PROJECT_MANAGEMENT/  # tasks, reports, risks\n├── 03_LEGAL/               # contracts, NDAs, compliance\n├── 04_RESEARCH/            # topics, objectives, summaries\n├── 05_ENGINEERING/         # architecture, specs, decisions\n├── 06_DATA/                # raw → staging → processed pipeline\n├── 97_MEDIA_LIBRARY/       # shared reusable assets\n├── 98_DELIVERABLES/        # final external outputs\n├── 99_ARCHIVE/             # historical storage\n└── activity.log            # append-only audit trail\n```\n\nEach subject (event, task, topic, objective, datasource) lives in its own directory with a `META.yaml` file that makes it searchable, filterable, and machine-readable.\n\n\u003e **Note:** All directory and file names are case-sensitive, including on Windows. `01_EVENTS` and `01_events` are different paths. Always use the exact casing shown above.\n\n---\n\n## Features\n\n- **Create projects** from opinionated templates in seconds\n- **Add subjects** interactively or fully non-interactively via flags — events, tasks, topics, objectives, datasources\n- **Fuzzy search** across all metadata fields: names, tags, participants, notes, dates, locations\n- **Non-interactive search** via `--term` and `--type` flags for scripting pipelines\n- **Edit subject metadata** directly in your preferred editor — metadata index synced automatically on close\n- **Archive subjects** interactively or directly by UUID — moves to `99_ARCHIVE/`\n- **Rename subjects** interactively or directly by UUID — updates directory, metadata, and all cross-references\n- **Open subject directories** in your preferred file manager\n- **Sync** project metadata with manually edited subject files\n- **Track and untrack** existing projects without creating them\n- **Describe and summarize** projects with colored terminal output\n- **Default project** — set once, never pass `-d` again\n- **Activity log** — every create, edit, and archive appended to `activity.log` at project root\n- **Version control ready** — filesystem layout is designed to work naturally with Git, rsync, Syncthing, or any file watcher\n- **Pipe-friendly output** — chain with `grep`, `sed`, `cut`, and other UNIX tools\n- **Self-documenting** — `operatree explain` renders the full directory philosophy in your terminal\n\n---\n\n## Installation\n\n### Linux / macOS\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/hanymamdouh82/operatree/main/install.sh | sh\n```\n\nNo tools required beyond `curl`. The script auto-detects your OS and architecture, downloads the right binary, and installs it to `/usr/local/bin`.\n\n### Windows\n\nOpen PowerShell and run:\n\n```powershell\nirm https://raw.githubusercontent.com/hanymamdouh82/operatree/main/install.ps1 | iex\n```\n\nNo tools required. Installs to `%USERPROFILE%\\bin` and adds it to your PATH automatically. Restart your terminal after installation.\n\n### Manual download\n\nDownload the binary for your platform directly from the [Releases page](https://github.com/hanymamdouh82/operatree/releases):\n\n| File                          | Platform                       |\n| ----------------------------- | ------------------------------ |\n| `operatree-linux-amd64`       | Linux x86-64                   |\n| `operatree-linux-arm64`       | Linux ARM (Raspberry Pi, etc.) |\n| `operatree-darwin-amd64`      | macOS Intel                    |\n| `operatree-darwin-arm64`      | macOS Apple Silicon            |\n| `operatree-windows-amd64.exe` | Windows x86-64                 |\n\nRename the downloaded file to `operatree` (or `operatree.exe` on Windows) and place it in a directory on your `PATH`.\n\n### From source\n\nRequires Go 1.26 or higher.\n\n```bash\ngit clone https://github.com/hanymamdouh82/operatree.git\ncd operatree\nmake install\n```\n\nInstalls to `/usr/local/bin` on Linux and macOS. May prompt for `sudo` if the directory is not writable.\n\n---\n\n## Quick Start\n\n**1. Initialize configuration**\n\n```bash\noperatree init\n```\n\nSets up the config file with your standard projects directory, preferred editor, and file manager. Run once before anything else.\n\n**2. Create a new project**\n\n```bash\noperatree create myproject -t dev\n```\n\nCreates the full directory structure and registers the project in config. Use `operatree show templates` to list available templates.\n\n**3. Set a default project**\n\n```bash\noperatree use               # pick from tracked projects interactively\noperatree show default      # show current default\n```\n\nOnce set, all commands use it automatically — no `-d` flag needed.\n\n**4. Add a subject**\n\n```bash\noperatree add event\noperatree add task\noperatree add topic\noperatree add objective\noperatree add datasource\n```\n\nLaunches an interactive form to capture metadata. Every creation is logged to `activity.log`. Use flags to skip the form entirely:\n\n```bash\noperatree add event --name \"Site Visit\" --date 2026-06-01 --location Cairo --participants \"Alex,Sara\"\noperatree add task --name \"Prepare Report\" --owner Alex --status active --related-events \"Site Visit\"\n```\n\n**5. Find anything**\n\n```bash\noperatree find                         # browse all subjects interactively\noperatree find cairo                   # fuzzy search across all metadata\noperatree find event cairo             # filter by type, then fuzzy search\noperatree find --term cairo --plain    # non-interactive, raw YAML output\n```\n\n**6. Edit and open**\n\n```bash\noperatree edit                    # find a subject, open META.yaml in editor\noperatree edit event cairo        # filter first, then open in editor\noperatree open                    # find a subject, open its directory in file manager\noperatree open task report        # filter first, then open directory\n```\n\nThe metadata index is updated automatically when the editor closes — no manual sync needed.\n\n**7. Describe and summarize**\n\n```bash\noperatree describe                # styled project structure\noperatree describe --plain        # raw YAML for piping\noperatree summary                 # counts, types, status breakdown\noperatree explain                 # directory philosophy guide\n```\n\n**8. Track existing projects**\n\n```bash\noperatree track -d /path/to/project    # add an existing project to tracked list\noperatree untrack myproject            # remove by name\noperatree untrack -d .                 # remove by path\n```\n\n---\n\n## Commands\n\n| Command                           | Description                                           |\n| --------------------------------- | ----------------------------------------------------- |\n| `operatree init`                  | Initialize OperaTree configuration                    |\n| `operatree create [name]`         | Create a new project from a template                  |\n| `operatree use`                   | Set default project interactively                     |\n| `operatree goto`                  | Open a tracked project in the file manager            |\n| `operatree add [type]`            | Add a new subject interactively or via flags          |\n| `operatree find [type] [term]`    | Fuzzy-find subjects across all metadata               |\n| `operatree edit [type] [term]`    | Find a subject and open its metadata in editor        |\n| `operatree open [type] [term]`    | Find a subject and open its directory in file manager |\n| `operatree rename [type] [term]`  | Find a subject and rename it                          |\n| `operatree archive [type] [term]` | Find a subject and move it to `99_ARCHIVE/`           |\n| `operatree sync`                  | Sync project metadata with subject files on disk      |\n| `operatree track`                 | Add a project to tracked list                         |\n| `operatree untrack [name]`        | Remove a project from tracked list                    |\n| `operatree describe`              | Describe project directory structure                  |\n| `operatree summary`               | Project summary with counts and status                |\n| `operatree explain`               | Print directory philosophy guide                      |\n| `operatree show [verb]`           | Show OperaTree configuration and state                |\n| `operatree version`               | Print version, commit, and build date                 |\n\n### Flags\n\n| Flag                  | Short | Command                     | Description                                  |\n| --------------------- | ----- | --------------------------- | -------------------------------------------- |\n| `--dest`              | `-d`  | all                         | Project directory to operate on              |\n| `--template`          | `-t`  | `create`                    | Project template (required)                  |\n| `--verbose`           | `-v`  | `create`                    | Print directory structure after creation     |\n| `--plain`             | `-p`  | `describe`, `find`          | Output raw YAML instead of styled view       |\n| `--name`              | —     | `add`                       | Subject name — triggers non-interactive mode |\n| `--date`              | —     | `add`                       | Subject date                                 |\n| `--notes`             | —     | `add`                       | Subject notes                                |\n| `--tags`              | —     | `add`                       | Comma-delimited tags                         |\n| `--location`          | —     | `add event`                 | Event location                               |\n| `--participants`      | —     | `add event`                 | Comma-delimited participants                 |\n| `--owner`             | —     | `add task`                  | Task owner                                   |\n| `--status`            | —     | `add task`, `add objective` | Subject status                               |\n| `--related-events`    | —     | `add task`                  | Comma-delimited related event names          |\n| `--related-objective` | —     | `add topic`                 | Related objective name                       |\n| `--outputs`           | —     | `add task`, `add objective` | Comma-delimited outputs                      |\n| `--source`            | —     | `add datasource`            | Data origin                                  |\n| `--source-link`       | —     | `add datasource`            | URL or path to source data                   |\n| `--source-objective`  | —     | `add datasource`            | Related objective                            |\n| `--source-datasize`   | —     | `add datasource`            | Dataset size                                 |\n| `--term`              | `-t`  | `find`                      | Search term for non-interactive mode         |\n| `--type`              | `-s`  | `find`                      | Subject type filter for non-interactive mode |\n| `--uuid`              | `-u`  | `rename`, `archive`         | Subject UUID for non-interactive mode        |\n| `--new-name`          | `-n`  | `rename`                    | New subject name (required with `--uuid`)    |\n\n### Project Directory Resolution\n\nWhen `-d` is not provided, OperaTree resolves the project directory in this order:\n\n1. Current directory contains a `META.yaml` → use current directory\n2. A default project is set in config → use it\n3. Neither → error with a helpful message\n\n---\n\n## Subject Types\n\nA subject is any trackable unit of work or knowledge within a project.\n\n| Type         | Purpose                                       | Key Fields                                          |\n| ------------ | --------------------------------------------- | --------------------------------------------------- |\n| `event`      | A project activity — visit, workshop, meeting | date, location, participants, tags                  |\n| `task`       | A unit of work with a lifecycle               | owner, status, related events, outputs              |\n| `topic`      | A knowledge concept or domain area            | tags, notes, related objective                      |\n| `objective`  | A goal driving research and decisions         | status, outputs, tags                               |\n| `datasource` | An external dataset or data feed              | source, sourceLink, sourceObjective, sourceDataSize |\n\nAll subjects share common fields: `name`, `date`, `tags`, `notes`. Type-specific fields use `omitempty` so they never appear in unrelated subjects.\n\n---\n\n## Search\n\nOperaTree builds a rich search index from all subject metadata — not just names. A single fuzzy query matches across the full depth of the project tree including nested modules:\n\n- Name, tags, participants\n- Notes, date, location\n\n**Interactive mode** — launches the finder with a live preview panel:\n\n```bash\noperatree find cairo              # matches events in Cairo, notes mentioning Cairo, etc.\noperatree find event emissions    # filter by type, then search\noperatree find                    # open interactive browser across all subjects\n```\n\n**Non-interactive mode** — returns results directly for scripting:\n\n```bash\noperatree find --term cairo --type event          # filter events for \"cairo\"\noperatree find --term done --type task --plain    # output as raw YAML\n\n# Bulk archive all done tasks via pipeline\noperatree find --term done --type task --plain \\\n  | grep uuid \\\n  | awk '{print $2}' \\\n  | xargs -I{} operatree archive --uuid {}\n```\n\nThe interactive finder shows a tabulated list with module path breadcrumbs and a live preview panel for the selected subject. The same finder is used by `edit` and `open`.\n\n---\n\n## Editing Metadata\n\nSubject metadata files (`META.yaml`) are plain YAML and can be edited directly in any text editor. OperaTree embraces this — it never locks your data.\n\nThe `edit` command finds a subject and opens its `META.yaml` in your configured editor:\n\n```bash\noperatree edit                    # interactive finder, then open in editor\noperatree edit event cairo        # filter first, then open\n```\n\nThe project metadata index is updated automatically when the editor closes — no manual sync needed.\n\nFor edits made outside of OperaTree (direct file edits, git pulls, Syncthing syncs), run `sync` manually to reconcile:\n\n```bash\noperatree sync\n```\n\n---\n\n## Activity Log\n\nEvery subject creation, edit, and archive is recorded in `activity.log` at the project root:\n\n```\n2026-05-20T10:08:39Z    CREATE    event    \"Site Visit Cairo\"    hany@optiplex7040    v0.1.0\n2026-05-20T11:22:14Z    CREATE    task     \"Prepare Report\"      hany@optiplex7040    v0.1.0\n2026-05-20T14:05:03Z    EDIT      task     \"Prepare Report\"      hany@optiplex7040    v0.1.2\n2026-05-20T16:45:00Z    ARCHIVE   task     \"Old Vendor Analysis\" hany@optiplex7040    v0.1.2\n```\n\nTab-separated columns: `timestamp`, `action`, `type`, `name`, `user@host`, `version`.\n\nThe log is append-only and pipe-friendly:\n\n```bash\ngrep CREATE activity.log | cut -f3 | sort | uniq -c    # count creations by type\ngrep event activity.log                                  # all event actions\ngrep hany activity.log | tail -20                        # last 20 actions by user\ngrep ARCHIVE activity.log | cut -f4                      # names of archived subjects\n```\n\nAdd `activity.log` to `.gitignore` to exclude it, or commit it for a full audit trail — both are valid.\n\n---\n\n## Configuration\n\nConfig lives at `~/.config/operatree/operatree.yaml` (see platform-specific paths below):\n\n```yaml\nstandardDir: /home/user/projects\neditor: nvim # fallback to $EDITOR if not set\nfileManager: nautilus # no fallback if not set\ndefault:\n  name: myproject\n  absPath: /home/user/projects/myproject\n  template: dev\nprojects:\n  - name: myproject\n    absPath: /home/user/projects/myproject\n    template: dev\n  - name: research-2026\n    absPath: /home/user/projects/research-2026\n    template: research\ndaemon:\n  enabled: false\n  host: localhost\n  port: 7070\n  dbDriver: sqlite\n  dsn: \"\"\n```\n\n| Field         | Description                                                         |\n| ------------- | ------------------------------------------------------------------- |\n| `standardDir` | Default base directory for new projects                             |\n| `editor`      | Editor for `operatree edit`. Falls back to `$EDITOR`                |\n| `fileManager` | File manager for `operatree open` and `operatree goto`. No fallback |\n| `default`     | Default project used when `-d` is not provided                      |\n| `projects`    | All tracked projects                                                |\n| `daemon`      | Reserved for future daemon configuration                            |\n\n**Config file locations:**\n\n| Platform    | Location                                                 |\n| ----------- | -------------------------------------------------------- |\n| Linux       | `~/.config/operatree/operatree.yaml`                     |\n| Linux (XDG) | `$XDG_CONFIG_HOME/operatree/operatree.yaml`              |\n| macOS       | `~/Library/Application Support/operatree/operatree.yaml` |\n| Windows     | `%APPDATA%\\operatree\\operatree.yaml`                     |\n\nRun `operatree init` again at any time to reconfigure — the prompt pre-fills your current values.\n\n---\n\n## Version Control \u0026 Backup\n\nOperaTree's filesystem-first design makes it naturally compatible with any version control or backup strategy. Because everything is plain files and directories, no special integration is needed — your existing tools already work.\n\n### The two-layer model\n\n**Layer 1 — Change detection:** a file watcher monitors the project directory and triggers an action when files are added, modified, or deleted. Tools that fit this role include:\n\n- [`watchexec`](https://github.com/hanymamdouh82/watchexec) — a config-driven directory watcher with flexible trigger rules, delays, and exclusion lists. Can run as a systemd service.\n- [`inotifywait`](https://github.com/inotify-tools/inotify-tools) — Linux-native filesystem event monitoring\n- [`fswatch`](https://github.com/emcrisostomo/fswatch) — cross-platform file change monitor\n\n**Layer 2 — The action:** what happens when a change is detected. Common strategies:\n\n| Strategy              | Tool         | Best for                                     |\n| --------------------- | ------------ | -------------------------------------------- |\n| Local version history | `git commit` | Full history, diffs, branching               |\n| Local + remote backup | `git push`   | Team sharing, offsite backup                 |\n| Directory sync        | `rsync`      | Mirror to another machine or drive           |\n| Continuous sync       | `syncthing`  | Real-time multi-device sync without a server |\n| Cloud backup          | `rclone`     | S3, Google Drive, Dropbox, etc.              |\n\n### Example: watchexec + operatree sync\n\n```yaml\n# conf.yml — auto-sync metadata index on any project change\ndirs:\n  /home/user/projects/myproject:\n    bin: operatree\n    args:\n      - sync\n      - -d\n      - /home/user/projects/myproject\n    stdout: true\n    delay: 5\n    exclude:\n      - .git\n      - activity.log\n```\n\n```bash\nwatchexec -c /home/user/.config/watchexec/conf.yml\n```\n\nOperaTree does not ship a built-in watcher or backup engine — this is an intentional design decision. The right strategy depends on your environment, team size, and infrastructure. The filesystem layout is the contract; how you protect it is yours to decide.\n\n---\n\n## Roadmap\n\nOperaTree is in active development. The foundation is filesystem-first and stable. Future layers will be built on top without breaking it.\n\n| Phase                       | Description                                                                                         | Status         |\n| --------------------------- | --------------------------------------------------------------------------------------------------- | -------------- |\n| CLI                         | Filesystem engine, YAML metadata, fuzzy search, interactive and non-interactive forms, activity log | 🚧 Alpha       |\n| Version control integration | Native watchexec/git hooks, configurable watcher and action backends                                | 📋 Planned     |\n| Index sidecar               | SQLite mirror for fast queries, no filesystem writes                                                | 📋 Planned     |\n| Daemon                      | API over the index, sync engine, configuration-driven engine selection                              | 📋 Planned     |\n| Semantic search             | Embeddings and vector search over subject metadata and file contents                                | 📋 In Progress |\n| Web platform                | Multi-user, web UI, enterprise features (commercial)                                                | 💡 Vision      |\n\n---\n\n## Contributing\n\nOperaTree welcomes contributions. The most impactful areas for community contribution are:\n\n- **New subject types** — extend the type system with domain-specific subjects\n- **New project templates** — add templates for research, legal, creative, and other domains\n- **Search enhancements** — improve matching algorithms, ranking, relevance\n- **Version control backends** — watcher strategies, git hooks, rsync/syncthing integration\n- **Output formatters** — new ways to display and export project data\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for the full architecture guide.\n\n---\n\n## License\n\nCopyright 2026 Hany Mamdouh\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n\n\u003e Commercial modules (daemon, semantic search, web platform) will be released\n\u003e under a separate commercial license when available. The CLI tool will always\n\u003e remain Apache 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanymamdouh82%2Foperatree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhanymamdouh82%2Foperatree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhanymamdouh82%2Foperatree/lists"}