Skip to content

overview.md

Latest commit

 

History

History
79 lines (63 loc) · 3.87 KB

overview.md

File metadata and controls

79 lines (63 loc) · 3.87 KB
Raw

Overview

OmaTrack is an Omarchy shell plugin for tracking billable and non-billable work time per client and project. It shows a live timer in the bar (with pause/resume/stop), offers a one-click quick-start popup, and a dashboard window for managing entries, clients, projects, reports, invoices, and settings.

Plugin id: io.github.sh1d0w.omatrack.

The three plugin kinds

One plugin, three kinds (declared in manifest.json):

Kind File What it is
bar-widget BarWidget.qml Center-section label: current task + elapsed, or ◷ idle
service Service.qml Headless singleton: state, helper channel, IPC
panel Dashboard.qml Toplevel dashboard window (7 tabs)

Because both bar-widget and panel kinds are present, the shell's summon/toggle routing (shell.qml) targets the panel entry: omarchy-shell shell toggle io.github.sh1d0w.omatrack opens the dashboard, not the popup — there is no CLI to open the bar popup, which opens only by clicking the bar widget.

File map

manifest.json        kinds, category, defaultSection: center
Service.qml          headless engine (see architecture.md)
BarWidget.qml        bar label + popup host          (bar-widget.md)
Popup.qml            anchored quick-start popup      (popup.md)
Dashboard.qml        toplevel window, 7 tabs         (dashboard.md)
omatrack.py         state engine + CLI, single writer
components/          TaskForm, EntryForm, DateRangeBar, DatePicker, EntryRow, ClientRow,
                     ProjectRow, InvoiceRow, PaginationBar, CardOverlay, LabeledField,
                     EmptyMessage
views/               TimerView, EntriesView, ClientsView, ProjectsView,
                     ReportsView, InvoicesView, SettingsView

Quick start

# from this repo — single local-install command (full form in AGENTS.md → Dev loop)
DEST=~/.config/omarchy/plugins/io.github.sh1d0w.omatrack && rm -rf "$DEST" && mkdir -p "$DEST" && cp -R --parents manifest.json Service.qml BarWidget.qml Popup.qml Dashboard.qml omatrack.py components views "$DEST" && chmod +x "$DEST/omatrack.py" && (omarchy-shell shell rescanPlugins >/dev/null 2>&1 || true)
omarchy plugin enable io.github.sh1d0w.omatrack

Then:

  • Click the ◷ in the center bar section → quick-start popup.

  • Start a client + project first (via the popup's form after creating them in the dashboard, or via the CLI). A started task always needs client, project and a description:

    python3 omatrack.py client-add --name "Acme"
python3 omatrack.py project-add --client-id c_XXXXXXXXXXXX --name "Landing page"
python3 omatrack.py start --client-id c_… --project-id p_… --description "Landing hero"

  • Open the dashboard: omarchy-shell shell toggle io.github.sh1d0w.omatrack (or the popup's Dashboard button).

Feature index

Feature Doc
Architecture, state, performance budget architecture.md
Bar widget (center section) bar-widget.md
Quick-start popup popup.md
Dashboard window (tabs, keyboard) dashboard.md
Entries (filters, add/edit/delete) entries.md
Clients & projects (CRUD rules) clients-projects.md
Reports & CSV/HTML export reports-export.md
Invoices invoices.md
Settings & CLI settings.md