{"id":31565431,"url":"https://github.com/paatre/recall","last_synced_at":"2026-04-13T20:32:11.130Z","repository":{"id":317962733,"uuid":"1069525684","full_name":"paatre/recall","owner":"paatre","description":"This tool collects your activity from various sources and generates a summarized, chronological timeline for a specific day. It's designed to give you a \"perfect memory\" of what you've worked on, making it easier to fill out timesheets, write progress reports, or simply reflect on your day.","archived":false,"fork":false,"pushed_at":"2026-04-02T18:39:06.000Z","size":179,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T05:59:36.267Z","etag":null,"topics":["aggregator","cli","firefox","gitlab","google-calendar","python","shell-history","slack","uv"],"latest_commit_sha":null,"homepage":"","language":"Python","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/paatre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-04T05:18:56.000Z","updated_at":"2026-04-02T18:39:10.000Z","dependencies_parsed_at":"2025-10-04T07:17:31.866Z","dependency_job_id":"a664b248-67bb-47f9-aa93-d44fe4284ed1","html_url":"https://github.com/paatre/recall","commit_stats":null,"previous_names":["paatre/recall"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paatre/recall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paatre%2Frecall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paatre%2Frecall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paatre%2Frecall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paatre%2Frecall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paatre","download_url":"https://codeload.github.com/paatre/recall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paatre%2Frecall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: 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":["aggregator","cli","firefox","gitlab","google-calendar","python","shell-history","slack","uv"],"created_at":"2025-10-05T07:06:51.118Z","updated_at":"2026-04-13T20:32:11.099Z","avatar_url":"https://github.com/paatre.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Recall\n\nThis tool collects your activity from various sources and generates a\nsummarized, chronological timeline for a specific day. It's designed to give\nyou a \"perfect memory\" of what you've worked on, making it easier to fill out\ntimesheets, write progress reports, or simply reflect on your day.\n\n## Prerequisites\n\n- Python 3.10 or higher\n- `uv` tool for building and installing the package, and also for development\n  purposes\n- Access to the data sources you want to collect activity from (e.g., Google\nCalendar, GitLab, Slack, etc.) and the necessary permissions to read the data\n\n## Collectors\n\nThese are the data sources currently supported:\n\n- Firefox browsing history\n- Google Calendar events\n- GitLab activity\n- Slack messages\n- Shell command history\n\n## Installation and usage\n\n### Clone the repository\n\n```bash\ngit clone https://github.com/paatre/recall.git\ncd recall\n```\n\n### Install the package\n\nThere are multiple ways to install the package but the recommended way is to\nis to use `uv tool`.\n\nUsing `uv tool`:\n```\nuv tool install .\n```\n\nThis will create a command line tool called `recall` which\ngets installed into your `$HOME/.local/bin` directory so you can run it from\nanywhere.\n\nAlternatively, you can install the tool with something like `pipx`.\n\n### Usage\n\nAfter installation, you can run the tool using:\n\n```bash\nrecall\n```\n\nThe tool will generate a timeline for today's activity by default. You can also\nspecify a date in `YYYY-MM-DD` format, or use keywords like `today`, `yesterday`, or a weekday (e.g., `friday` or `mon`) to get the activity for that specific day.\n\n```bash\nrecall 2025-01-01\nrecall yesterday\nrecall friday\n```\n\n### Example output\n\n```\n$ recall YYYY-MM-DD\n    - ✅ Firefox collector found X events.\n    - ✅ Calendar collector found X events.\n    - ✅ GitLab collector found X events.\n    - ✅ Shell collector found X events.\n    - ✅ Slack collector found X events.\n🤖 Generating timesheet with Github...\n\n--- Timesheet Draft for YYYY-MM-DD ---\n\n╭─ [09:00 - 10:00] (1.0h) | Context: Calendar: Daily Sync, Slack: #team-alpha ──────────────╮\n│ ↳ \"Attended daily stand-up and discussed project requirements with the team.\"             │\n│ ├── [09:00:00] [Calendar] Meeting: Daily Sync                                             │\n│ ├── [09:15:22] [Slack] Message in #team-alpha: \"Here are the notes from today.\"           │\n│ └── [09:45:10] [Firefox] Project Requirements - Confluence                                │\n╰───────────────────────────────────────────────────────────────────────────────────────────╯\n\n╭─ [10:00 - 12:00] (2.0h) | Context: GitLab: alpha-project, Shell: local dev ───────────────╮\n│ ↳ \"Implemented the new authentication flow and created a merge request.\"                  │\n│ ├── [10:05:12] [Shell] git checkout -b feature/auth-flow                                  │\n│ ├── [10:30:45] [Firefox] How to use JWT tokens - Google Search                            │\n│ ├── [11:45:30] [Shell] git commit -m \"feat: add jwt auth\"                                 │\n│ └── [11:55:10] [GitLab] Opened merge request: Add JWT authentication                      │\n╰───────────────────────────────────────────────────────────────────────────────────────────╯\n```\n\n## Configuration\n\nThe tool uses a YAML configuration file to manage collectors and their settings.\n\n### Global configuration file\n\nCreate a global configuration file in the `.config` directory in your home\ndirectory:\n\n```bash\nmkdir -p ~/.config/recall\ntouch ~/.config/recall/config.yaml\n```\n\nAdd your settings and secrets to this `config.yaml` file. Here is a template:\n\n```yaml\nsources:\n  - id: \"Firefox\"\n    type: \"firefox\"\n    enabled: true\n    config: {}\n\n  - id: \"Calendar\"\n    type: \"gcalendar\"\n    enabled: true\n    config: {}\n\n  - id: \"GitLab\"\n    type: \"gitlab\"\n    enabled: true\n    config:\n      url: \"\"\n      private_token: \"\"\n      user_id: 0\n\n  - id: \"Shell\"\n    type: \"shell\"\n    enabled: true\n    config: {}\n\n  - id: \"Slack\"\n    type: \"slack\"\n    enabled: true\n    config:\n      user_token: \"\"\n\nllm:\n  provider: \"github\" # \"github\", \"openai\", or \"custom\"\n  api_key: \"\"        # Optional. If empty, uses 'gh' CLI for github, or OPENAI_API_KEY\n  base_url: \"\"       # Optional. Set to override default API endpoint\n  custom_instructions: \"\"\n```\n\nRead the following section for collector-specific setup instructions.\n\n### Collector-specific configurations\n\nThis section describes the setup required for each collector.\n\n#### Google Calendar\n\n- Follow the [Google Calendar API Python Quickstart](https://developers.google.com/calendar/api/quickstart/python)\nto enable the API, configure the OAuth consent screen and download your\n`credentials.json`.\n- Place the `credentials.json` file in `~/.config/recall/`.\n- The first time you run the tool, it will open a browser window for you to\nauthorize access. This will create a `token.json` and store it in the\n`~/.config/recall/` directory for future runs so that you\ndon't need to authorize again.\n\n#### GitLab\n\nAdd your GitLab settings to your `config.yaml` file under the GitLab source config:\n\n```yaml\n    config:\n      url: \"https://your.gitlab-instance.com\"\n      private_token: \"your_personal_access_token\"\n      user_id: 12345\n```\n\n#### Slack\n\n\u003e [!note]\n\u003e This collector is not available yet to public use. This is currently being\n\u003e tested internally.\n\n- You need a Slack User Token. You can generate one for your workspace.\n- Add the token to your `config.yaml` file under the Slack source config:\n\n```yaml\n    config:\n      user_token: \"xoxp-...\"\n```\n\n#### Shell history\n\nThis collector reads from a custom history file located at\n`~/.recall.log` by default. This is required to generate\ntimestamps even if the commands are executed in different shells (e.g., when\nusing `tmux`). It is recommended to add these lines to your `.bashrc` to\nensure this:\n\n```bash\nHISTTIMEFORMAT=\"%Y-%m-%dT%H:%M:%S%z \"\n\nexport PROMPT_LOG_FILE=\"$HOME/.recall_shell_history.log\"\n\nlog_prompt_command() {\n    local last_command=$(history 1)\n    if [[ \"$last_command\" =~ ^[[:space:]]*[0-9]+[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\+?[0-9]{4}[[:space:]]+(.*) ]]; then\n        local command_to_log=\"${BASH_REMATCH[1]}\"\n        local current_time=$(date +\"%Y-%m-%dT%H:%M:%S%z\")\n        echo \"$current_time $command_to_log\" \u003e\u003e \"$PROMPT_LOG_FILE\"\n    fi\n}\n\nexport PROMPT_COMMAND=\"log_prompt_command\"\n```\n\n#### Firefox\n\nNo special configuration is needed. The collector automatically tries to find\nyour Firefox `places.sqlite` database.\n\nHere are the default locations that are supported currently:\n\n- Linux: `~/.mozilla/firefox/` or `snap/firefox/common/.mozilla/firefox`\n- macOS: `Library/Application Support/Firefox`\n- Windows: `AppData/Roaming/Mozilla/Firefox/Profiles`\n\n## Extending the Tool\n\nYou can easily add new data sources by creating a new collector.\n\n1. Create a new file in the `src/recall/collectors/` directory (e.g., `my_collector.py`).\n2. In this file, create a class that inherits from `BaseCollector` (from `collectors/base.py`).\n3. Implement the `name()` and `collect()` methods. The `collect()` method must be `async` and return a list of `Event` objects.\n4. Add your new collector class to the `get_collector_map()` function in `src/recall/main.py`.\n5. Enable and configure it in your `~/.config/recall/config.yaml` file.\n\n## Contributing\n\nContributions are welcome! Especially in the form of new collectors for new\ndata sources. This project started as a personal tool but hopefully others will\nfind it useful too with more data sources.\n\nPlease fork the repository and create a pull request with your changes. Make\nsure to follow the existing code style. For example, use Ruff for linting and\nformatting. Keeping test coverage high and writing tests for new features is\nalso appreciated. You can run the tests using:\n\n```bash\nuv run pytest\n```\n\nYou can also use the convenient `pytest-watcher` to automatically run tests on\nfile changes:\n\n```bash\nuv run ptw\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaatre%2Frecall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaatre%2Frecall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaatre%2Frecall/lists"}