When something breaks during engineering work, I want to reconstruct more than the commands I typed. I want to know which configuration or resource changed, what failed afterward, and what I did before it recovered. WakeTrail grew around that question.
I am building it as a local forensic timeline for DevOps work. The Go CLI records shell activity and brings it together with observations from Git, Docker and Compose, systemd, Kubernetes, and Terraform/OpenTofu. The core recorder and review workflow are implemented; the project is now in pre-release development and v1 hardening.
Stack: Go, Cobra, SQLite, Bash integration, Lip Gloss, and a modular collector framework.
Keeping the action and the observation together
The Bash integration records command timing, working directory, exit status, duration, and Git context. Approved diagnostic output can accompany the command. Collectors add resource observations so the trail can show what happened around that work.
A session can be reviewed in the terminal and exported as Markdown:
waketrail start compose-investigation
waketrail mark "Checking the deployment baseline"
# Perform the investigation in the instrumented Bash shell.
waketrail stop
waketrail show compose-investigation
waketrail export compose-investigation -o compose-investigation.mdThe timeline brings those records into one chronological view. Correlation still needs restraint: a state change following a command is evidence of sequence, and the relevant resource and scope help establish a relationship. Timing alone does not prove that the command caused the change.
(add screenshot of a real WakeTrail session showing the command, observed failure, investigation, and recovery)
Making a Compose deployment readable
A Compose operation can affect several containers. Displaying every transition as an unrelated card makes the investigation harder to follow.
I worked on grouping the observed effects under the Compose activity while preserving the underlying events. Project attribution uses actual Compose labels, which matters when a deployment's project name differs from its directory. Ambiguous project evidence should remain ungrouped.
The resulting cards share fields for the deployment, effects, scope, and command. Counts describe the affected containers and labelled services that were observed. They do not establish that every service in a project was present or ready.
The repository includes regression cases for project matching, ambiguous projects, observed transitions, and shared terminal/export fields. The hardening notes also record a live Compose up/down smoke test in the installed CLI.
Keeping the exported account consistent
The terminal view and Markdown export use the same semantic timeline reconstruction. The export path delegates to the shared builder:
func buildExportEvents(commands []storage.CommandEvent, timeline []storage.TimelineEvent) []displayEvent {
return buildDisplayEvents(commands, timeline, false)
}That choice keeps the saved account aligned with the trail I reviewed. The shared card-field builder carries the same activity details into both formats, while verbose terminal output provides access to lower-level evidence.
See the export implementation.
Treating captured evidence as sensitive data
A tool that records troubleshooting can also record credentials. I made capture policy part of the recorder rather than relying on every user to remember which output might be sensitive.
Secret-prone inspections, Git patch output, and arbitrary web-response bodies retain command metadata without capturing their output. Eligible diagnostics receive best-effort redaction before new SQLite writes, and the recorder independently checks the capture policy.
Persisted output is limited to 64 KiB per stream. Oversized ordinary output retains a head and tail with an omission marker; privacy-sensitive truncation can withhold the tail. Local state and new exports use restricted permissions.
Those choices trade completeness for more controlled evidence handling. Redaction has limits, existing recordings are not rewritten, and shared exports still need review. The security document records those boundaries.
What still needs to earn a v1 release
The CI workflow checks formatting, runs Go vet and the test suite, and builds the project. Release readiness also depends on behavior those checks cannot establish by themselves: clean installation, reliable shell integration, collector failure reporting, and a clear recording lifecycle.
One important current behavior is that waketrail stop ends the named session while leaving the Bash hook loaded. The hook can record outside a named session. Bounded retro retention and its controls still need to be defined and implemented.
The configurable retro buffer, automatic incident preservation, incident-focused reports, and Omarchy widget are planned work. The proposed TUI and desktop investigation interface remain exploratory.
The immediate goal is a trustworthy CLI release: understandable capture, explicit gaps, consistent evidence, and documentation that matches the installed behavior. The larger interface ideas can build on that foundation.