feat: add autostart and pid management to daemon (#3180)

2 files changed, 28 insertions, 1 deletions

diff --git a/docs/docs/configuration/config.md b/docs/docs/configuration/config.md
index 31980ed1..7836dc6c 100644
--- a/docs/docs/configuration/config.md
+++ b/docs/docs/configuration/config.md
@@ -688,6 +688,18 @@ Add the new section to the bottom of your config file
 enabled = true
 ```
 
+### autostart
+
+Default: `false`
+
+Automatically start and manage the daemon when needed.
+This is not compatible with `systemd_socket = true`.
+If a legacy experimental daemon is already running, restart it manually once before using autostart.
+
+```toml
+autostart = false
+```
+
 ### sync_frequency
 
 Default: `300`
@@ -710,6 +722,16 @@ Where to bind a unix socket for client -> daemon communication
 
 If XDG_RUNTIME_DIR is available, then we use this directory instead.
 
+### pidfile_path
+
+Default:
+
+```toml
+pidfile_path = "~/.local/share/atuin/atuin-daemon.pid"
+```
+
+Path to the daemon pidfile used for process coordination.
+
 ### systemd_socket
 
 Default `false`
diff --git a/docs/docs/reference/daemon.md b/docs/docs/reference/daemon.md
index 22088254..49080e88 100644
--- a/docs/docs/reference/daemon.md
+++ b/docs/docs/reference/daemon.md
@@ -20,9 +20,14 @@ Add the following to the bottom of your Atuin config file
 ```toml
 [daemon]
 enabled = true
+autostart = true
 ```
 
-Then, run `atuin daemon`. This might make sense in a tmux session, systemd unit, etc. Once it's ready for wider use, we will handle this setup for you.
+With `autostart = true`, the CLI will automatically start and manage a local daemon for history hook calls.
+If you use systemd socket activation, keep `autostart = false`.
+If a legacy experimental daemon is already running, autostart cannot upgrade it in-place. Restart the daemon manually once.
+
+If you prefer running the daemon yourself (for example via systemd/tmux), keep `autostart = false` and run `atuin daemon`.
 
 ## Extra config