tsudo

tsudo is a temporary sudo proxy for AI agents. A human enters the real sudo password locally, then gives the agent a short-lived temporary token. The agent can run privileged commands only through tsudo, and every proxied command is printed and logged.

Install

npm install -g @duyld/tsudo

Install the Claude Code skill from GitHub:

npx skills add duylddev/tsudo

Usage

Create a temporary token with the default 10 minute lifetime:

tsudo

Create a token for a specific duration:

tsudo 30m
tsudo 1h

Run a privileged command through the proxy:

tsudo run --token <temporary-token> -- apt update

Show recent logs:

tsudo logs 10

Check logs for suspicious commands:

tsudo check

Show active session status:

tsudo status

Clear the active session:

tsudo clear

AI agent workflow

1. The agent loads the tsudo skill.
2. The agent checks whether tsudo is installed.
3. If needed, the agent asks before running npm install -g @duyld/tsudo.
4. The human runs tsudo or tsudo <duration> and enters the real sudo password locally.
5. The human gives the temporary token to the agent.
6. The agent shows every privileged command before it runs.
7. The agent runs privileged commands only with tsudo run --token <temporary-token> -- ....

Security model

tsudo is designed to avoid sending the real sudo password to an AI agent. The real password remains on the local machine and is used only by the tsudo process to feed sudo -S.

Important limitations:

• The current session file is protected with user-only file permissions, but the password is still present locally for the token lifetime.
• Any process with access to the same user account may be able to read files owned by that user.
• The temporary token should be treated as sensitive until it expires.
• tsudo check uses conservative pattern matching. It can miss dangerous commands and can flag harmless commands.
• This tool does not replace careful human review of privileged operations.

Logs are stored as JSONL under ~/.tsudo/logs.jsonl. Logs include command arguments, working directory, exit status, and danger classification. They do not include the real sudo password, temporary token, command stdin, or environment variables.

Development

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run

Publishing

Before publishing, run:

npm run prepublishOnly
npm publish --access public

Do not publish until the package metadata and repository URL are final.