{"id":23296511,"url":"https://github.com/elizaOS/characterfile","last_synced_at":"2025-08-22T02:31:25.879Z","repository":{"id":255953585,"uuid":"832730961","full_name":"ai16z/characterfile","owner":"ai16z","description":"A simple file format for character data","archived":false,"fork":false,"pushed_at":"2024-09-19T15:43:43.000Z","size":231,"stargazers_count":120,"open_issues_count":7,"forks_count":40,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-18T01:14:01.379Z","etag":null,"topics":["agent-simulations","agents","characters","llm"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ai16z.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}},"created_at":"2024-07-23T15:54:42.000Z","updated_at":"2024-12-17T19:27:25.000Z","dependencies_parsed_at":"2024-09-08T04:26:39.859Z","dependency_job_id":"ae86d1a9-3e59-4450-a146-268b7ff150c7","html_url":"https://github.com/ai16z/characterfile","commit_stats":null,"previous_names":["lalalune/tweets2character","ai16z/characterfile"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai16z%2Fcharacterfile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai16z%2Fcharacterfile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai16z%2Fcharacterfile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ai16z%2Fcharacterfile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ai16z","download_url":"https://codeload.github.com/ai16z/characterfile/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230547695,"owners_count":18243226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["agent-simulations","agents","characters","llm"],"created_at":"2024-12-20T07:12:02.730Z","updated_at":"2025-08-22T02:31:25.866Z","avatar_url":"https://github.com/ai16z.png","language":"JavaScript","readme":"# Characterfile\n\nThe goal of this project is to create a simple, easy-to-use format for generating and transmitting character files. You can use these character files out of the box with [Eliza](https://github.com/elizaOS/eliza) or other LLM agents.\n\n## Getting Started - Generate A Characterfile From Your Twitter\n\n1. Open Terminal. On Mac, you can press Command + Spacebar and search for \"Terminal\". If you're using Windows, use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)\n2. Type `npx tweets2character` and run it. If you get an error about npx not existing, you'll need to install Node.js\n3. If you need to install node, you can do that by pasting `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash` into your terminal to install Node Version Manager (nvm)\n4. Once that runs, make a new terminal window (the old one will not have the new software linked) and run `nvm install node` followed by `nvm use node`\n5. Now copy and paste `npx tweets2character` into your terminal again.\n6. NOTE: You will need to get a [Claude](https://console.anthropic.com/settings/keys) or [OpenAI](https://platform.openai.com/api-keys) API key. Paste that in when prompted\n7. You will need to get the path of your Twitter archive. If it's in your Downloads folder on a Mac, that's ~/Downloads/\u003cname of archive\u003e.zip\n8. If everything is correct, you'll see a loading bar as the script processes your tweets and generates a character file. This will be output at character.json in the directory where you run `npx tweets2character`. If you run the command `cd` in the terminal before or after generating the file, you should see where you are.\n\n## Schema\n\nThe JSON schema for the character file is [here](schema/character.schema.json). This also matches the expected format for [OpenAI function calling](https://platform.openai.com/docs/guides/function-calling).\n\nTypescript types for the character file are [here](examples/types.d.ts).\n\n## Examples\n\n### Example Character file\nBasic example of a character file, with values that are instructional\n[examples/example.character.json](examples/example.character.json)\n\n### Basic Python Example\nRead the example character file and print the contents\n[examples/example.py](examples/example.py)\n\n### Python Validation Example\nRead the example character file and validate it against the JSON schema\n[examples/validate.py](examples/validate.py)\n\n### Basic JavaScript Example\nRead the example character file and print the contents\n[examples/example.mjs](examples/example.mjs)\n\n### JavScript Validation Example\nRead the example character file and validate it against the JSON schema\n[examples/validate.mjs](examples/validate.mjs)\n\n# Scripts\n\nYou can use the scripts the generate a character file from your tweets, convert a folder of documents into a knowledge file, and add knowledge to your character file.\n\nMost of these scripts require an OpenAI or Anthropic API key.\n\n## tweets2character\n\nConvert your twitter archive into a .character.json\n\nFirst, download your Twitter archive here: https://help.x.com/en/managing-your-account/how-to-download-your-x-archive\n\nYou can run tweets2character directly from your command line with no downloads:\n\n```sh\nnpx tweets2character\n```\n\nNote: you will need node.js installed. The easiest way is with [nvm](https://github.com/nvm-sh/nvm).\n\nThen clone this repo and run these commands:\n\n```sh\nnpm install\nnode scripts/tweets2character.js twitter-2024-07-22-aed6e84e05e7976f87480bc36686bd0fdfb3c96818c2eff2cebc4820477f4da3.zip # path to your zip archive\n```\n\nNote that the arguments are optional and will be prompted for if not provided.\n\n## folder2knowledge\n\nConvert a folder of images and videos into a .knowledge file which you can use with [Eliza](https://github.com/lalalune/eliza). Will convert text, markdown and PDF into normalized text in JSON format.\n\nYou can run folder2knowledge directly from your command line with no downloads:\n\n```sh\nnpx folder2knowledge \u003cpath/to/folder\u003e\n```\n\n```sh\nnpm install\nnode scripts/folder2knowledge.js path/to/folder # path to your folder\n```\n\nNote that the arguments are optional and will be prompted for if not provided.\n\n## knowledge2character\n\nAdd knowledge to your .character file from a generated knowledge.json file.\n\nYou can run knowledge2character directly from your command line with no downloads:\n\n```sh\nnpx knowledge2character \u003cpath/to/character.character\u003e \u003cpath/to/knowledge.knowledge\u003e\n```\n\n```sh\nnpm install\nnode scripts/knowledge2character.js path/to/character.character path/to/knowledge.knowledge # path to your character file and knowledge file\n```\n\nNote that the arguments are optional and will be prompted for if not provided.\n\n## Chat Export Processing\n\nProcess WhatsApp chat exports to create character profiles.\n\nYou can run chats2character directly from your command line with no downloads:\n\nnpx chats2character -f path/to/chat.txt -u \"Username\"\nnpx chats2character -d path/to/chats/dir -u \"John Doe\"\n\nOr if you have cloned the repo:\n\nnpm install\nnode scripts/chats2character.js -f path/to/chat.txt -u \"Username\"\nnode scripts/chats2character.js -d path/to/chats/dir -u \"John Doe\"\n\nOptions:\n-u, --user           Target username as it appears in chats (use quotes for names with spaces)\n-f, --file           Path to single chat export file\n-d, --dir            Path to directory containing chat files\n-i, --info           Path to JSON file containing additional user information\n-l, --list           List all users found in chats\n--openai [api_key]   Use OpenAI model (optionally provide API key)\n--claude [api_key]   Use Claude model (default, optionally provide API key)\n\nExamples:\n# Provide API key directly:\nnpx chats2character -d whatsapp/chats --openai sk-...\nnpx chats2character -d whatsapp/chats --claude sk-...\n\n# Use stored/cached API key:\nnpx chats2character -d whatsapp/chats --openai\nnpx chats2character -d whatsapp/chats --claude\n\nThe script will look for API keys in the following order:\n1. Command line argument if provided\n2. Environment variables (OPENAI_API_KEY or CLAUDE_API_KEY)\n3. Cached keys in ~/.eliza/.env\n4. Prompt for key if none found\n\nExample user info file (info.txt):\nThe user is a mother of two, currently living in Madrid. She works as a high school teacher\nand has been teaching mathematics for over 15 years. She's very active in the school's\nparent association and often organizes educational events. In her free time, she enjoys\ngardening and cooking traditional Spanish recipes.\n\nThe file should be a plain text file with descriptive information about the user. This\ninformation helps provide context to better understand and analyze the chat messages.\n\nThe script will:\n1. Extract messages from the specified user\n2. Process content in chunks\n3. Generate a character profile\n4. Save results to character.json\n\nNote: WhatsApp chat exports should be in .txt format with standard WhatsApp export formatting:\n[timestamp] Username: message\n\nFor usernames with spaces, make sure to use quotes:\n[timestamp] John Doe: message\n\n# License\n\nThe license is the MIT license, with slight modifications so that users are not required to include the full license in their own software. See [LICENSE](LICENSE) for more details.\n","funding_links":[],"categories":["🤖 AI \u0026 Machine Learning"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FelizaOS%2Fcharacterfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FelizaOS%2Fcharacterfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FelizaOS%2Fcharacterfile/lists"}