{"id":35885661,"url":"https://github.com/jcaldwell-labs/my-context","last_synced_at":"2026-01-22T19:28:44.108Z","repository":{"id":324719827,"uuid":"1073862516","full_name":"jcaldwell-labs/my-context","owner":"jcaldwell-labs","description":"the my-context agent journal","archived":false,"fork":false,"pushed_at":"2026-01-15T13:09:48.000Z","size":27257,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T21:40:05.642Z","etag":null,"topics":["agent-workflow","ai-agents","claude-code","cli","context-management","developer-tools","golang","productivity"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcaldwell-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2025-10-10T18:29:45.000Z","updated_at":"2026-01-15T13:09:52.000Z","dependencies_parsed_at":"2026-01-16T11:09:21.088Z","dependency_job_id":null,"html_url":"https://github.com/jcaldwell-labs/my-context","commit_stats":null,"previous_names":["jcaldwell-labs/my-context"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/jcaldwell-labs/my-context","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcaldwell-labs%2Fmy-context","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcaldwell-labs%2Fmy-context/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcaldwell-labs%2Fmy-context/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcaldwell-labs%2Fmy-context/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcaldwell-labs","download_url":"https://codeload.github.com/jcaldwell-labs/my-context/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcaldwell-labs%2Fmy-context/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28669093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T17:07:18.858Z","status":"ssl_error","status_checked_at":"2026-01-22T17:05:02.040Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-workflow","ai-agents","claude-code","cli","context-management","developer-tools","golang","productivity"],"created_at":"2026-01-08T20:12:56.196Z","updated_at":"2026-01-22T19:28:44.101Z","avatar_url":"https://github.com/jcaldwell-labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# My-Context\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8.svg)](https://golang.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n\u003e _Track what you're working on, not just what you've done._\n\nA cross-platform CLI tool for managing developer work contexts with notes, file associations, and timestamps.\n\n## Why My-Context?\n\nMost developers context-switch constantly but lose track of _why_ they made decisions, _what_ files were involved, and _when_ they stopped mid-task. My-context solves this by creating lightweight, timestamped work journals that follow you across sessions.\n\n**Key benefits:**\n\n- **Instant context capture** — Start tracking in one command, add notes as you go\n- **Automatic transitions** — Switching contexts stops the previous one automatically\n- **Plain text storage** — All data stored as human-readable files you can grep, version control, or edit\n- **Zero lock-in** — No database, no cloud dependency, no vendor tie-in\n- **Cross-platform** — Works identically on Windows, Linux, macOS, and WSL\n\n**Perfect for:**\n\n- Developers who context-switch frequently between tasks\n- Teams wanting lightweight decision documentation\n- Anyone who's asked \"what was I doing on that ticket last week?\"\n- Pomodoro/time-boxing practitioners tracking work sessions\n- AI-assisted coding workflows that need session memory\n\n## Demo\n\n```bash\n# Start working on a feature\n$ my-context start \"Implement user auth\"\nContext started: Implement_user_auth\n\n# Capture decisions as you go\n$ my-context note \"Using JWT tokens for stateless auth\"\n$ my-context note \"Added refresh token rotation\"\n\n# Associate relevant files\n$ my-context file src/auth/jwt.go\n$ my-context file tests/auth_test.go\n\n# Urgent bug? Just start a new context\n$ my-context start \"Hotfix: login timeout\"\n# Previous context automatically stopped\n\n# Review what you worked on\n$ my-context show\n```\n\n## Quick Start\n\n### Install\n\n**Linux/macOS/WSL (one-liner):**\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/jcaldwell-labs/my-context/main/scripts/curl-install.sh | bash\n```\n\n**Or download binaries** from [Releases](https://github.com/jcaldwell-labs/my-context/releases):\n\n- `my-context-linux-amd64` — Linux (x86_64)\n- `my-context-darwin-amd64` — macOS Intel\n- `my-context-darwin-arm64` — macOS Apple Silicon\n- `my-context-windows-amd64.exe` — Windows\n\n**Build from source:**\n\n```bash\ngit clone https://github.com/jcaldwell-labs/my-context.git\ncd my-context\ngo build -o my-context ./cmd/my-context/\n```\n\n### Your First Context\n\n```bash\n# 1. Start a context\nmy-context start \"My first task\"\n\n# 2. Add a note\nmy-context note \"Getting started with my-context\"\n\n# 3. See your context\nmy-context show\n\n# 4. List all contexts\nmy-context list\n```\n\n## Features\n\n### Core Context Management\n\n| Command        | Alias | Description                       |\n| -------------- | ----- | --------------------------------- |\n| `start \u003cname\u003e` | `s`   | Create and activate a new context |\n| `stop`         | `p`   | Stop the active context           |\n| `show`         | `w`   | Display current context details   |\n| `list`         | `l`   | List all contexts with filters    |\n| `history`      | `h`   | Show context transition history   |\n\n### Notes \u0026 Files\n\n| Command       | Alias | Description                            |\n| ------------- | ----- | -------------------------------------- |\n| `note \u003ctext\u003e` | `n`   | Add timestamped note to active context |\n| `file \u003cpath\u003e` | `f`   | Associate file with active context     |\n| `touch`       | `t`   | Record activity timestamp              |\n\n### Organization (Sprint 2+)\n\n| Command          | Alias | Description                     |\n| ---------------- | ----- | ------------------------------- |\n| `export \u003cname\u003e`  | `e`   | Export context to markdown/JSON |\n| `archive \u003cname\u003e` | `a`   | Archive completed contexts      |\n| `delete \u003cname\u003e`  | `d`   | Permanently remove a context    |\n\n### Analytics \u0026 Automation\n\n| Command  | Alias | Description                                             |\n| -------- | ----- | ------------------------------------------------------- |\n| `stats`  |       | Time tracking aggregation (--today, --week, --month)    |\n| `record` | `r`   | Clipboard recording mode - auto-capture pastes as notes |\n\n### Advanced Features\n\n**Project Grouping:**\n\n```bash\nmy-context start \"Phase 1\" --project myapp\nmy-context list --project myapp\n```\n\n**Filtering \u0026 Search:**\n\n```bash\nmy-context list --limit 5\nmy-context list --search \"auth\"\nmy-context list --archived\n```\n\n**JSON Output:**\n\n```bash\nmy-context show --json | jq .\n```\n\n## Use Cases\n\n### Daily Development Workflow\n\n```bash\n# Morning: start your day\nmy-context start \"Sprint 42 - User dashboard\"\nmy-context note \"Planning: add charts, fix pagination\"\n\n# As you work\nmy-context note \"Charts library: chose recharts over chart.js\"\nmy-context file src/components/Dashboard.tsx\n\n# Context switch happens\nmy-context start \"Code review: PR #234\"\n# Previous context auto-stopped with timestamp\n```\n\n### Git Integration\n\n```bash\n# In .git/hooks/post-commit\nmy-context note \"Committed: $(git log -1 --pretty=%B)\"\n```\n\n### End-of-Day Review\n\n```bash\nmy-context list --limit 10\nmy-context export \"Sprint 42 - User dashboard\"\n```\n\n## Data Storage\n\nAll data stored in `~/.my-context/` as plain text:\n\n```\n~/.my-context/\n├── state.json              # Active context pointer\n├── transitions.log         # Transition history\n└── Context_Name/           # Per-context directory\n    ├── meta.json           # Context metadata\n    ├── notes.log           # Timestamped notes\n    ├── files.log           # File associations\n    └── touch.log           # Activity timestamps\n```\n\nOverride location: `export MY_CONTEXT_HOME=/custom/path`\n\n### Database Backend (PostgreSQL)\n\nFor teams, high-volume usage, or centralized context storage, my-context supports PostgreSQL:\n\n```bash\n# Enable database backend\nexport MY_CONTEXT_HOME=db\nexport DATABASE_URL=\"host=localhost port=5432 user=myuser password=mypass dbname=dev_state sslmode=disable\"\n\n# Or use connection URL format\nexport DATABASE_URL=\"postgres://myuser:mypass@localhost:5432/dev_state?sslmode=disable\"\n```\n\n**Partitions** — Isolate contexts by project:\n\n```bash\n# Each partition gets its own schema\nexport MY_CONTEXT_HOME=db:project-alpha\nexport MY_CONTEXT_HOME=db:project-beta\n\n# List all partitions\nmy-context partitions\n\n# Query across partitions\nmy-context list --all-partitions\n```\n\n**When to use database backend:**\n\n| Use Case         | File Backend   | Database Backend  |\n| ---------------- | -------------- | ----------------- |\n| Single developer | ✅ Recommended | Works             |\n| Team sharing     | ❌ Manual sync | ✅ Recommended    |\n| 100+ contexts    | Slower         | ✅ 10-400x faster |\n| Backup/restore   | File copy      | pg_dump           |\n| Cross-machine    | ❌ Manual      | ✅ Built-in       |\n\n**Migration:** Existing file-based contexts remain in `~/.my-context/`. Database mode creates new contexts in PostgreSQL. There's no automatic migration—use `export` to move contexts if needed.\n\n## Documentation\n\n- **[Getting Started Guide](docs/guides/GETTING-STARTED.md)** — Full installation and first steps\n- **[Triggers Tutorial](docs/tutorials/TRIGGERS-TUTORIAL.md)** — Automation with signals and watches\n- **[Troubleshooting](docs/guides/TROUBLESHOOTING.md)** — Common issues and solutions\n- **[CLAUDE.md](CLAUDE.md)** — Architecture and development guide\n\n## Comparison\n\n| Feature               | my-context | git stash    | tmux sessions | note apps |\n| --------------------- | ---------- | ------------ | ------------- | --------- |\n| Context tracking      | Yes        | No           | No            | Manual    |\n| Automatic transitions | Yes        | No           | No            | No        |\n| File associations     | Yes        | Yes (staged) | No            | Manual    |\n| Timestamped notes     | Yes        | No           | No            | Yes       |\n| Plain text storage    | Yes        | Binary       | N/A           | Varies    |\n| Cross-platform        | Yes        | Yes          | Unix only     | Varies    |\n| CLI-first             | Yes        | Yes          | Yes           | No        |\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Development:**\n\n```bash\ngo build -o my-context ./cmd/my-context/\ngo test ./...\n```\n\n**Integration Testing with BATS:**\n\n```bash\n# Install BATS (https://bats-core.readthedocs.io/)\n# macOS: brew install bats-core\n# Debian/Ubuntu: apt install bats\n\n# Run file mode tests\nmake test-bats\n\n# Run all tests (database tests require DATABASE_URL_TEST)\nDATABASE_URL_TEST=\"postgres://...\" make test-bats-all\n\n# Or use the runner script directly\n./scripts/run-integration-tests.sh file    # File mode only\n./scripts/run-integration-tests.sh db      # Database mode only\n./scripts/run-integration-tests.sh all     # Both suites\n```\n\nTest suites include:\n\n- **file_mode.bats** — Core commands with file-based storage (17 tests)\n- **database_mode.bats** — Database backend commands (19 tests)\n- **synthetic_workflows.bats** — Real developer workflow simulations (8 tests)\n\n**Key principles:**\n\n1. Unix philosophy — Do one thing well\n2. Plain text — All storage human-readable\n3. Test-first — TDD approach required\n4. Cross-platform — Windows, Linux, macOS\n\n## Roadmap\n\nSee [.github/planning/ROADMAP.md](.github/planning/ROADMAP.md) for upcoming features.\n\n## Community\n\n- **Issues:** [GitHub Issues](https://github.com/jcaldwell-labs/my-context/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/jcaldwell-labs/my-context/discussions)\n\n## Related Projects\n\nmy-context is part of the [jcaldwell-labs](https://github.com/jcaldwell-labs) organization. Sister projects you may find useful:\n\n**Terminal/TUI Applications:**\n| Project | Description | Synergy with my-context |\n|---------|-------------|-------------------------|\n| [my-grid](https://github.com/jcaldwell-labs/my-grid) | ASCII canvas editor with vim-style navigation | Track grid editing sessions and design decisions |\n| [boxes-live](https://github.com/jcaldwell-labs/boxes-live) | Real-time ASCII box drawing with joystick support | Document box layout iterations during prototyping |\n| [terminal-stars](https://github.com/jcaldwell-labs/terminal-stars) | Starfield animation for terminals | — |\n| [atari-style](https://github.com/jcaldwell-labs/atari-style) | Retro visual effects and shaders for terminal apps | — |\n| [smartterm-prototype](https://github.com/jcaldwell-labs/smartterm-prototype) | Smart terminal with readline-like features | Integrate my-context commands into smart workflows |\n\n**CLI Tools:**\n| Project | Description | Synergy with my-context |\n|---------|-------------|-------------------------|\n| [fintrack](https://github.com/jcaldwell-labs/fintrack) | Personal finance tracking CLI (Go) | Shared CLI patterns and Go architecture |\n| [tario](https://github.com/jcaldwell-labs/tario) | Terminal-based platformer game (Go) | — |\n\n**Game Engines \u0026 Agents:**\n| Project | Description | Synergy with my-context |\n|---------|-------------|-------------------------|\n| [adventure-engine-v2](https://github.com/jcaldwell-labs/adventure-engine-v2) | Multiplayer text adventure engine (C) | Track game development sessions and world-building notes |\n| [capability-catalog](https://github.com/jcaldwell-labs/capability-catalog) | Skill/capability definitions for AI agents | my-context provides session memory for agent workflows |\n\n## License\n\n[MIT License](LICENSE) — Free for personal and commercial use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcaldwell-labs%2Fmy-context","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcaldwell-labs%2Fmy-context","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcaldwell-labs%2Fmy-context/lists"}